Cherwell Asset Management API - Version 2.5

Release notes

CAM API v2.5 is compatible with Cherwell Asset Management v13.0 and higher.

The following changes were made to the API in v2.5.

• Update authentication to use UTF-8 strings.

Introduction

The CAM API is a collection of web services that allows you to interchange data with external systems. Typical uses might involve:

• Adding purchase information from an external corporate purchasing system.
• Updating the status of purchases, line items, or inventoried items based on external data.
• Extracting information (for all purchases, leases, computers, licenses, etc.) for correlation with another application.

The following services are provided:

• General.svc (version information)
• Order.svc (purchases and leases)
• Contract.svc (contracts, contract templates, and types)
• LineItem.svc (hardware, hardware maintenance, software, software maintenance, and software upgrade line items)
• LineItemDetail.svc (detail items within a line item, such as a single license or computer)
• Inventory.svc (computers, license units, and other assets)
• Manufacturer.svc (manufacturers and vendors)
• User.svc (users)
• Group.svc (groups)

Installation

CAM API v2.5 is for use with Cherwell Asset Management v13.0 and must be installed manually. IIS must also be configured manually. The API is delivered in a file called CAMAPI.zip which can be found in the CAM/ folder of the distribution .ZIP file.

To install the API:

1. Install Cherwell Asset Management as normal using camsetup.exe.
2. Extract the contents of the CAMAPI.zip file to the esmweb folder created by setup in the default web site root folder (by default, c:\inetpub\wwwroot\esmweb). This should result in a new folder CAMAPI under esmweb.
3. In IIS, create a virtual directory pointing to c:\inetpub\wwwroot\esmweb\CAMAPI.
4. In IIS, create an application pool for CAMAPI (use the same settings as for Purchasing - e.g., in IIS7 and above, Managed Pipeline must be Classic, and on 64bit OSes, Enable 32-Bit Applications must be True).
5. In IIS, turn the CAMAPI virtual directory into an application pointing to the new application pool.
6. Modify the web.config file in the CAMAPI folder - set the connectionString property value to use your CAM database (use web.config under Purchasing for reference).

1. To allow updating purchasing records, in IIS configure the .svc extension for the CAMAPI virtual directory to allow PUT (by default only GET,POST,HEAD,DEBUG are allowed).
2. To allow deleting purchasing records:
   1. In IIS, configure the .svc extension for the CAMAPI virtual directory to allow DELETE.
   2. In Windows Explorer, configure Security for the CAMAPI folder to allow the Internet Guest Account these additional permissions: Read & Execute, List Folder Contents, Read.

1. Modify the web.config. Uncomment the <system.webServer> section.
2. In Windows Explorer, configure Security for the CAMAPI folder to allow "[machine name]\IUSR" these permissions: Read & Execute, List Folder Contents, Read, Write.

1. Modify the web.config. Uncomment the <system.webServer> section.
2. In Windows Explorer, configure Security for the CAMAPI folder to allow "[machine name]\IUSR" these permissions: Read & Execute, List Folder Contents, Read, Write.
3. Configure the .svc handler in Control Panel > Programs and Features > Turn Windows features on or off > .Net Framework 4.5 Advanced Services > WCF Services. Check "HTTP Activation".
4. You might also need to turn on Windows Forms Authentication. In IIS Manager go to the CAMAPI application and change the Authentication configuration. Enable both Anonymous Authentication and Forms Authentication.

Upgrading

CAM API v2.5 is for use with Cherwell Asset Management v13.0 and must be upgraded manually. The API is delivered in a file called CAMAPI.zip which can be found in the CAM/ folder of the distribution .ZIP file.

To upgrade the API:

1. Install/Upgrade Cherwell Asset Management as normal using camsetup.exe.
2. Stop the application pool for CAMAPI. If you have an application pool called ESMAPI, delete it.
3. Delete the c:\inetpub\wwwroot\esmweb\CAMAPI folder and all its contents. If you have a folder called c:\inetpub\wwwroot\esmweb\ESMAPI, delete it and all of its contents.
4. Extract the contents of the CAMAPI.zip file to the esmweb folder in the default web site root folder (by default, c:\inetpub\wwwroot\esmweb). This should result in a new folder CAMAPI under esmweb.
5. Modify the web.config file in the CAMAPI folder - set the connectionString property value to use your CAM database (use web.config under Purchasing for reference).

1. In Windows Explorer, configure Security for the CAMAPI folder to allow the Internet Guest Account these additional permissions: Read & Execute, List Folder Contents, Read.

1. Modify the web.config. Uncomment the <system.webServer> section.
2. In Windows Explorer, configure Security for the CAMAPI folder to allow "[machine name]\IUSR" these permissions: Read & Execute, List Folder Contents, Read, Write.

1. Modify the web.config. Uncomment the <system.webServer> section.
2. In Windows Explorer, configure Security for the CAMAPI folder to allow "[machine name]\IUSR" these permissions: Read & Execute, List Folder Contents, Read, Write.

REST design

CAM API is a collection of web services that structures information using REST design principles. This means:

• Each object in the system (purchase, line item, user, group, etc.) has a unique URI.
• The HTTP verbs POST, GET, PUT, and DELETE are used to do CRUD (Create, Update, Delete) operations (respectively).
• The information is organized in a tree structure, and reading or writing a value involves providing a path to the node that is to be operated on.
• The response to each operation provides a status code and (except for DELETE) a representation of the data requested, created, or updated.

How data is read, added, updated, and deleted

The HTTP verbs GET, POST, PUT, and DELETE are used to tell the web service what it is you want to do. Query parameters and the HTTP message body provide the parametric data required.

Reading data — GET

For the GET request, you just provide a URI. The web service reads the query parameters you provide and returns the requested data if it can.

Each result returned contains a URI field that uniquely identifies each object.

The response is an HTTP status code 200 (OK) if the GET succeeded.

Adding new data — POST

The POST request uses a URI to identify the kind of thing you want to create (such as order/purchase), and an XML message body (using the same schema generated by a GET) to provide the data to initialize the new object. The output of the POST is the XML that describes the new object, including the URI assigned by the system.

To add a new order with several line items, you would first create the order (purchase or lease) and remember its assigned URI. Then you would create any line items, filling in the line item's order URI with the URI of the new order. Then you would do the same for any line item details (serial numbers and assignments).

The response is an HTTP status code 201 (Created) if the POST succeeded.

Updating existing data — PUT

To update existing data, you do a PUT and provide the URI of the record you want to update. You must also provide XML data with updated data for each field in the record. Fields without values will be set to a suitable default.

To guard against updating records that are out of date (have been modified since the last time you read them), there is a VersionStamp field. You must get the current record before updating it, because the update will fail if the VersionStamp doesn't match what is currently saved.

The PUT response is an XML representation of the updated record.

The response is an HTTP status code 200 (OK) if the PUT succeeded.

Deleting existing data — DELETE

To delete something, you simply use a DELETE command with a URI that identifies the record to be deleted. Referential integrity rules will delete any other objects "owned" by what the system deletes.

The response is an HTTP status code 200 (OK) if the object was deleted successfully.

How information is represented

The web service provides and consumes data in XML. A few important notes:

• Dates are always formatted as yyyy-MM-dd.
• When searching for dates, you can use the following formats: yyyyMMdd, yyyy-MM-dd, yyyy/MM/dd
• You must specify the fields in the XML in the order shown in the service documentation.
• Currency is formatted with a period as the decimal separator and no currency symbol. Please see the topic "Troubleshooting: Currency issues" in Purchasing for more information.
• Unless otherwise specified, the default values for fields are as follows:
• String: empty
• Currency and Number: 0
• Date: empty
• License type: Unmanaged
• Status type: empty

Here is the XML data for a purchase:

<Purchase>
  <Uri>http://myserver/CAMAPI/Order.svc/Purchase/3</Uri>
  <VersionStamp>2</VersionStamp>
  <Date>2010-01-05</Date>
  <Description>Expiring maintenance test</Description>
  <OrderNumber>9290930293029039</OrderNumber>
  <AccessProfile>Purchasing Administrator</AccessProfile>
  <PONumber />
  <TotalPrice>493.00000</TotalPrice>
  <Vendor>
    <Uri />
    <Name>Cherwell Software</Name>
  </Vendor>
  <Notes />
  <CreatedBy>Kathy</CreatedBy>
  <RelatedDocuments />
  <CustomFields>
    <CustomField>
      <Name>Division</Name>
      <Type>Text</Type>
      <Required>False</Required>
      <Value />
    </CustomField>
  </CustomFields>
  <LineItems>
    <Uri>http://myserver/CAMAPI/LineItem.svc/Software/License/219</Uri>
    <Uri>http://myserver/CAMAPI/LineItem.svc/Maintenance/Software/15</Uri>
  </LineItems>
  <InvoiceNumber>54-134</InvoiceNumber>
</Purchase>

Orders are either purchases or leases. In this example each field is labeled with a tag, and references to other things, such as line items, are represented as URIs. The URI for the order itself is provided in the first URI tag. If you present any of these URIs to the web service you will get back whatever the URI addresses.

Here is an example of a software line item:

<SoftwareLineItem>
  <Uri>http://myserver/CAMAPI/LineItem.svc/Software/License/219</Uri>
  <VersionStamp>2</VersionStamp>
  <Order>http://myserver/CAMAPI/Order.svc/Purchase/3</Order>
  <ItemType>Software</ItemType>
  <Name>Microsoft Office</Name>
  <Quantity>3</Quantity>
  <UnitPrice>499.00000</UnitPrice>
  <Status />
  <Contract>http://myserver/CAMAPI/Contract.svc/4</Contract>
  <Notes />
  <CustomFields>
    <CustomField>
      <Name>Location</Name>
      <Type>Text</Type>
      <Required>False</Required>
      <Value />
    </CustomField>
  </CustomFields>
  <Details>
    <Uri>http://myserver/CAMAPI/LineItemDetail.svc/Software/License/39410</Uri>
  </Details>
  <IncludesMaintenance>False</IncludesMaintenance>
  <Attributes>
    <Attribute>
       <Name>IncludesMaintenance</Name>
       <Description>Contract: Includes software maintenance (boolean)</Description>
       <Type>Boolean</Type>
       <Value>False</Value>
    </Attribute>
  </Attributes>
  <ManufacturerName>Microsoft Corporation</Manufacturer>
  <LicenseType>Per seat</LicenseType> 
  <LicenseUnit>
    <Uri>http://myserver/CAMAPI/Inventory.svc/LicenseUnit/261</Uri> 
    <Name>Microsoft Office</Name>
    <Type>License Unit</Type> 
    <Manufacturer>
      <Uri>http://myserver/CAMAPI/Manufacturer.svc/199</Uri> 
      <Name>Microsoft Corporation</Name>
    </Manufacturer>
    <LicenseType>Per seat</LicenseType> 
    <Licenses>5</Licenses> 
    <LastPerUnitCost>499.0000</LastPerUnitCost> 
  </LicenseUnit>
</SoftwareLineItem>

Each line item can itself be composed of a number of detail items. For example, a line item used to purchase five computers may have five detail records for the computers. Here is a line item detail for software:

<SoftwareDetail>
  <Uri>http://myserver/CAMAPI/LineItemDetail.svc/Software/License/39410</Uri> 
  <VersionStamp>2</VersionStamp>
  <LineItem>http://myserver/CAMAPI/LineItem.svc/Software/License/219</LineItem> 
  <Order>http://myserver/CAMAPI/Order.svc/Purchase/3</Order> 
  <Quantity>1</Quantity> 
  <SerialNumber>6493-2944-TOY1-1234</SerialNumber>
  <Assignment /> 
  <AssignmentGroup /> 
  <Notes /> 
  <ReconciledWith /> 
  <ActivationKey /> 
</SoftwareDetail>

And so forth. In each case the URI provides a unique reference to a record that the web service will retrieve when you do an HTTP GET operation.

Authorization

Applications that access CAM via the API do so as the CAM-API user. If Cherwell Asset Management is configured to use CAM authentication, the CAM-API user is pre-defined and has all rights required to call the API. However, if Cherwell Asset Management is configured to use CSM authentication, you must define the CAM-API user within CSM and give it certain rights prior to using the API.

• In CSM Administrator, create a user named CAM-API
• Specify that user's rights as CAM Purchasing Administrator
• Save the CAM-API user

API Authentication

The CAM API authenticates your requests to identify and verify who is sending the request. If you do not wish to authenticate, then you can edit the web.config file to turn off authentication. Search for "authenticationEnabled" and set its value to "false".

When authentication is enabled, you must provide the following items with each request so the request can be authenticated:

• Customer ID — Your CAM Customer ID. For evaluators, use 0.
• Signature — A request signature which is calculated using your Customer ID and a secret access key. The secret access key is "Express" by default. To change it, add a record to the options table in the CAM database with an optionname of "APIToken". Set the optionvalue to whatever secret access key you want to use. Restart the API application pool in IIS if you change the APIToken option value.
• Date — The time stamp of the request.

In the request header, you must send an authentication header containing your customer id and the request signature.

Authorization: <Customer ID>:<Signature>

You must also send a date header containing the timestamp. It can either be sent in the Date header or if you cannot set the Date header, then use the x-api-date header.

Date: <timestamp>
-or-
x-api-date: <timestamp>

To calculate your signature, do the following:

1. Start with the request URL and use only the path and query string. For example: If the request URL is http://myserver/CAMAPI/Order.svc/Purchase?orderby=date then you should only use /CAMAPI/Order.svc/Purchase?orderby=date when calculating the signature. Make sure it is not the URL escaped format of the request. For example, space should not be %20.
2. Lower case it.
3. Concatenate the timestamp.
4. Calculate the HMAC-MD5 signature.
5. Base64 encode it.

Example:

1. /CAMAPI/Order.svc/Purchase
2. /camapi/order.svc/purchase
3. /camapi/order.svc/purchaseMon, 28 Mar 2016 13:09:22 GMT
4. Calculate HMAC-MD5 signature. (non-printable)
5. Base64 encoded result : f+BnSiuw2C3Xpz11yAtpAA==

Request headers for the above example using evaluation customer ID:

x-apiversion: 2.5
Date: Mon, 28 Mar 2016 13:09:22 GMT
Authorization: 0:f+BnSiuw2C3Xpz11yAtpAA==

Java Sample Code for Calculating HMAC-MD5 Signatures. Note: Strings passed into this function are expected to be UTF-8 encoded.

import java.security.SignatureException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Signature {
   public static String calculateHMAC(String data, String key)
   throws java.security.SignatureException
   {
      String result;
      try {
         // get an hmac_md5 key from the raw key bytes
         SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), "HmacMD5");

         // get an hmac_md5 Mac instance and initialize with the signing key
         Mac mac = Mac.getInstance("HmacMD5");
         mac.init(signingKey);

         // compute the hmac on input data bytes
         byte[] rawHmac = mac.doFinal(data.getBytes());

         // base64-encode the hmac
         result = Base64.encode(rawHmac);

      } catch (Exception e) {
         throw new SignatureException("Failed to generate HMAC : " + e.getMessage());
      }
      return result;
   }
}

Versioning

The CAM API checks to ensure that the version of the API that you are using is compatible with your client application. In the request header, send a version header called "x-apiversion" containing the API version number. This header is required and if it is not present or is not the same version as the CAM API, then you will get a 400 (Bad Request) response and the response data will contain the error.

General.svc does not check the version information.

Request header with version information:

x-apiversion: 2.5

Access Profiles

When purchasing user profiles are enabled in the CAM Administrator, you can use access profiles in Purchasing to control who can view, edit, and create orders and contracts. A CAM API application is assumed to be the user "CAM-API" and if purchasing profiles are enabled, "CAM-API" must be a Purchasing administrator or CAM administrator, or in the Purchasing Administrator access profile.

If you add or update an order or contract through the CAM API and purchasing profiles are enabled you must specify an existing access profile. If purchasing profiles are disabled and you do not specify an access profile then it will be assigned to Purchasing Administrators.

For more information see the "Overview: Access profiles" topic in Purchasing help.