Organisations frequently face challenges in effectively managing their hardware assets and ensuring a unified repository that encompasses both internally procured items and those acquired from various external suppliers. ServiceNow's Hardware Asset Management (HAM) application addresses many of these complexities inherent in asset management. Among its notable features is the capability to import shipping information for assets sourced from multiple suppliers. However, the default process for this functionality is manual. For more information on the standard procedure, refer documentation - Advanced Shipment Notification (ASN).
In this article, we will explore how to integrate ServiceNow's ASN feature with its robust API framework to automate the creation of hardware assets ordered from external vendors. This involves leveraging scripted REST APIs to seamlessly integrate with external vendor systems.
Pre-requisites
- Process knowledge -
- Asset lifecycle from raising a Purchase Order until Delivery
- REST APIs
- Plugins - Hardware Asset Management (sn_hamp)
- Role - admin
Existing functionality
Manual import of asset information
- Navigate to All > Procurement > Orders > Import Shipment Notification to view the template download/upload page.
The downloaded Excel template will be a blank sheet containing various columns relevant to hardware asset data. By default, the expectation is that external vendors fill out this template and return it. A system administrator then manually uploads it into ServiceNow to create the necessary asset records.
What happens after a complete file is uploaded?
An import set is generated using all rows from the file, which subsequently initiates a standard transform map - 'Create Assets from ASN template import' - https://instance.service-now.com/nav_to.do?uri=sys_transform_map.do?sys_id=13196732f8821010fa9b01f8b...
The transform map includes few data quality validations that it executes prior to inserting the asset records into the Asset [alm_asset] table. For example, it validates whether a matching Purchase Order (PO) is present in the Purchase Order [proc_po] table and whether there are Line Items [proc_po_item] matching the Model number of the asset that is being imported. It is recommended to go through the transform map to understand all the validations that could stop the asset from being created. If all the checks pass, the assets are successfully inserted into ServiceNow.
Automating the Import Process with REST API
Incoming JSON payload
Let's assume that vendors will send the following payload structure into ServiceNow.
{
"assets": [
{
"account_name": "Account",
"asset_tag": "Tag123456",
"carrier": "Carrier",
"manufacturer": "Apple",
"model_id": "MR9V2LL/A",
"po_number": "PO00100046",
"serial": "SASR43242332TN",
"ship_to_address_city": "Plano",
"ship_to_address_state": "TX",
"ship_to_address_street": "6900 Dallas Pkwy",
"ship_to_address_zip": "75024",
"track_number": "6786787",
"vendor": "Vendor"
}
]
}Create a scripted API
- Set the application scope to 'Hardware Asset Management'.
- Navigate to 'Scripted REST APIs', create new.
- Enter the desired Name, API ID and save the record.
4. Under the 'Resources' related list, create new.
- Enter the desired Name, Relative Path.
- HTTP method needs to be 'POST'.
- Save the record.
5. Now for the script part of the record, it should resemble the following example.
- This is the most basic version to get started with. Code will need updates based on additional requirements, mappings, request structure, etc.
- Copyable version of the code can be found here.
- Reference - GlideImportSetTransformer
Test the scripted API
- Fill in a new Purchase Order [proc_po] and save the record.
- Notice that the status of the PO is 'Requested'.
- Notice that the 'Assets' related list is empty.
2. From the related lists, fill in a new Purchase order line item [proc_po_item] and save the record.
3. Navigate back to the Purchase Order [proc_po] record and click on the 'Order' button.
- Notice that the status of the PO has changed to 'Ordered'.
4. Navigate to All > System Web Services > Rest > Rest API Explorer and select the scripted API we created.
5. Copy the incoming JSON payload, modify it with the values corresponding to the PO and PO line item records. Paste it raw under Request Body and click Send.
6. If all the steps have been followed accurately, a successful response should be visible on the screen. Upon navigating back to the Purchase Order record that we created earlier, the 'Assets' related list would have a new asset record.
- Notice that the status of the PO has changed to 'Pending Delivery'.
Troubleshooting
Since we haven't thoroughly reviewed the default validations and transformations involved, there are instances where an import set may be created without the corresponding asset record being generated or linked to the purchase order. It's necessary to examine the import logs and review the 'Create Assets from ASN template import' transform map to identify and address any underlying issues causing this.
Next steps
- Set up user accounts with role based and web service access and test the configuration using Postman.
- Include additional field mappings in the incoming payload and adjust the transform mappings accordingly.
- Enhance error handling within the REST API script to prevent the creation of import sets from inaccurate data.
- Explore and experiment (only in sub-prod environments).
