The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes the Workorders API.
These APIs talk with any cloud-based management services. It contains seven primary action calls sent using the SOAP envelope over HTTP(s):
https://<server_address> :portnumber/nbapi/workorder
This call requests user authentication with the cloud service. The utility field technician must sign in to IoT FND before they can use the field tool. The username and password is encrypted and cached in the device for remote connections. Below is the definition for this action based on the Cisco HSL language:
String appVersion ## CG-NMS application version for version control String scriptVersion ## CG-NMS button script version for version control
“AUTH_OK” ## Authentication OK “AUTH_OK_NO_PERMISSION” ## Authentication OK but no permission to access resources “AUTH_OK_VER_MISMATCH” ## Authentication Fail - User/Pwd may be ok but the version is ## not expected "AUTH_FAIL" ## NOTE: This may never appear in the SOAP response as some ## web servers will return http status code 40x if auth fails. ## Both the 40x status code and AUTH_FAIL in the SOAP response ## are handled.
UserAuthResult userAuthResult ## Authentication result String expectAppVer ## [Optional] If the current app version ## needs to be upgraded String expectScriptVer ## If the current script version needs to be ## upgraded
Input:
UserAuthInfo userAuthInfo
Output:
UserAuthResponse RequestUserAuthenticationResponse
UserAuthResponseInfo userAuthResponse ## Authentication result
POST /nms/fieldtool HTTP/1.1 Host: sample.cisco.com:8080 Content-Length: nnn Authorization: Basic bW2eFaHU5K+ SOAPAction: http://workorder.nbapi.cgms.cisco.com/RequestUserAuthentication Connection: close Content-type: text/xml; charset=”UTF-8” User-Agent: Cisco Device Management Application <?xml version=”1.0” encoding=”utf-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> <SOAP-ENV:Body> <m:RequestUserAuthentication> <userAuthInfo> <appVersion>1.2.23.128</appVersion> <scriptVersion>2.3.4</scriptVersion> </userAuthInfo> </m:RequestUserAuthentication> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
HTTP/1.1 200 OK Content-type: text/xml; charset=”UTF-8” Content-Length: nnn <?xml version=”1.0” encoding=”utf-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”> <SOAP-ENV:Body> <m:RequestUserAuthenticationResponse xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> <userAuthResponse> <userAuthResult>AUTH_OK</userAuthResult> <expectAppVer>1.2.25.02</expectAppVer> <expectScriptVer>2.3.5</expectScriptVer> </userAuthResponse> </m:RequestUserAuthenticationResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
This call retrieves work authorizations from the cloud service. For security, the utility technician requests work authorizations from the management cloud service before they can complete the work order.
“ADMIN” ## Unlimited commands “TECH” ## Most commands and interface configure “VIEWER” ## Read only commands
String deviceId ## Device unique ID such as serial number String ssid ## WiFi SSID for a specific FAR device String passphrase ## WiFi Passphrase for a specific FAR device String firmwareVersion ## [Optional] Firmware version for this device. If present, ## CG-NMS needs to request it from NMS/Cloud String configurationId ## [Optional] Unique configuration profile id for this ## device. If present, Bahamas needs to request it from ## NMS/Cloud
String Algorithm
String Algorithm
String Algorithm
String Algorithm
TransformTheMethod TransformMethod
TransformsInfo Transforms DigestTheMethod DigestMethod String DigestValue
CanonicalizationTheMethod CanonicalizationMethod SignatureTheMethod SignatureMethod SignatureReference Reference ## Signed info reference
String X509SubjectName String X509Certificate
SignatureX509Data X509Data
SignatureSignedInfo SignedInfo String SignatureValue SignatureKeyInfo KeyInfo
String version ## Version of the schema for signed authorization String authId ## UID in the string format String authCreated ## Date String in UTC format String deviceId ## Device unique ID such as serial number String technician ## Name of the technician requesting the authorization UserRole userRole ## What role to manage the FAR String startDateTime ## Date in UTC string to indicate valid-from String endDateTime ## Date in UTC string to indicate valid-to XmlSignature Signature ## The signature info to be passed to FAR
SignedAuth signedAuth DeviceInfo deviceInfo ##[Optional]
SignedAuthorization[] signedAuthorization
Input:
String technicianUserName ## The technician username registered with NMS String workOrderNumber ## If the technician knows a specific name, he can ## put it here; otherwise put null string will ## retrieve all the orders assigned to him
Output:
SignedAuthorizationResponse RequestSignedAuthorizationResponse
POST /nbapi/workorder HTTP/1.1 Host: 128.154.157.111:8443 Content-Length: nnn SOAPAction: http://workorder.nbapi.cgms.cisco.com/RequestSignedAuthorization Authorization: Basic eWfqD54DefCdEf4B3aA= Connection: close Content-type: text/xml; charset=”UTF-8” User-Agent: Cisco Device Management Application <?xml version=”1.0” encoding=”utf-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> <SOAP-ENV:Body> <m:RequestSignedAuthorization> <technicianUserName>bob</technicianUserName> <workOrderNumber>abcd-efgh-hijk</workOrderNumber> </m:RequestSignedAuthorization> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
HTTP/1.1 200 OK Content-type: text/xml; charset=”UTF-8” Content-Length: nnn <?xml version=”1.0” encoding=”utf-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”> <SOAP-ENV:Body> <m:RequestSignedAuthorizationResponse xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> <signedAuthorization> <signedAuth> <version>1</version> <orderNumber>9429C098-495A-402C-9456-57F3CC7475BF</orderNumber> <authCreated>2011-09-20T03:48:28Z</authCreated> <userRole>tech</userRole> <technicianUserName>bob</technicianUserName> <deviceId>AB193AQ</deviceId> <startDate>2011-09-20T03:48:28Z</startDate> <endDate>2011-09-20T09:48:28Z</endDate> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <Reference URI=""> <Transforms> <TransformMethod Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <DigestValue>CpJhSOAalu8QJeUX2wiaGG0ZGEk=</DigestValue> </Reference> </SignedInfo> <SignatureValue> lgkxDOwRdaAUOvKTVyzbdsLL0c4ONB51LTmmOdWXCYMErwMSy53nWUencU h14cmR4rPsumdYWJzCqJik2oci6p8uMnLDCv8= </SignatureValue> <KeyInfo> <X509Data> <X509SubjectName> CN=My Name,O=Test Certificates Inc.,C=US </X509SubjectName> <X509Certificate> MIIB9zCCAWCgAwIBAgIERZwdkzANBgkqhkiG9w0BAQUFADBAMQswCQYD VQQGEwJVUzEfMB0GA1UEChMWVGVzdCBDZXJ0aWZpY2F0ZXMgSW5jLjE MA4GA1UEAxMHTXkgTmFtZTAeFw0wNzAxMDMyMTE4MTFaFw0zMTA4M ... </X509Certificate> </X509Data> </KeyInfo> </Signature> </signedAuth> <deviceInfo> <deviceId>AB193AQ</deviceId> <ssid>testfar</ssid> <passphrase>cisco123</passphrase> <firmwareVersion>1.2.3</firmwareVersion> <configurationId>123.234</configurationId> </deviceInfo> </signedAuthorization> <signedAuthorization> ... ... ... ... ... <signedAuthorization> </m:RequestSignedAuthorizationResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
This call uploads the service report to the cloud service. IoT FND tracks the service status for a work order, and prompts the utility technician to mark status field as job complete, job expired, job incomplete, and so on. Once work order status is reported, the work order can be safely removed from IoT FND. Work orders are archived on the NMS server.
“REPORT_OK” “REPORT_FAIL”
“Completed” # The work is done “Incomplete” # The work can not be completed due to some reasons “Expired” # The work authorization is expired
String orderNumber String deviceId String technicianUserName ServiceStaus status
ServiceReportResult result String comment ## [Optional]
ServiceStatusResponse serviceReportResponse
Input:
ServiceStatusReport [] serviceStatusReport
Output:
ServiceReportResponse UploadServiceReportResponse
POST /nms/fieldtool HTTP/1.1 Host: sample.cisco.com:8080 Content-Length: nnn Authorization: Basic bW2eFaHdD3K SOAPAction: [http://workorder.nbapi.cgms.cisco.com/UploadServiceReport ] Connection: close Content-type: text/xml; charset=”UTF-8” User-Agent: Cisco Device Management Application <?xml version=”1.0” encoding=”utf-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> <SOAP-ENV:Body> <m:UploadServiceReport> <serviceStatusReport> <orderNumber>9429C098-495A-402C-9456-57F3CC7475BF </orderNumber> <deviceId>AB193BQ</deviceId> <technicianUserName>Bob</technicianUserName> <status>Completed</status> </serviceStatusReport> <serviceStatusReport> <orderNumber>8688C098-495A-402C-2356-57F3CC7475BF </orderNumber> <deviceId>CC210EQ</deviceId> <technicianUserName>Alex</technicianUserName> <status>Expired</status> </serviceStatusReport> </m:UploadServiceReport> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
HTTP/1.1 200 OK Content-type: text/xml; charset=”UTF-8” Content-Length: nnn <?xml version=”1.0” encoding=”utf-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”> <SOAP-ENV:Body> <m:UploadServiceReportResponse xmlns:m="http://workorder.nbapi.cgms.cisco.com/"> <serviceReportResponse> <result>REPORT_FAIL</result> <comment>Syntax Error</comment> </serviceReportResponse> </m:UploadServiceReportResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>