Using 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
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 ## IoT-FND application version for version control
String scriptVersion ## IoT-FND 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,
## IoT-FND 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>