Call Properties - Authentication

What are Call Properties?

Call Properties allow for changing most of the settings in the IAP Service Instance Configuration for the adapter on a call-by-call basis. This is valuable when you want to change certain information, such as the domain a call is made against, the user you are authenticating as, whether the individual call is a stub/mock call, etc.

Call Properties are provided to the library by the adapter.js in the reqObj. They follow the same structure as the IAP Service Instance Configuration for the adapter. So, to replace the properties.authentication.username in the IAP Service Instance Configuration, you would pass in the new value in callProperties.authentication.username.

Not all values in the IAP Service Instance Configuration for the adapter can be replaced in the call properties. For example, throttling can not be turned off or on for individual calls as that does not make sense and can have major implications on how the adapter works.

iapMetadata

Newer adapters have an iapMetadata object that exposes callProperties. If you have an adapter that does this then you can pass the callProperties through the iapMetadata object. If not you will need to make the changes described below. If the adapter is an Itential open source adapter, you can request the Adapter Team add the iapMetadata object.

Changes to the adapter.js File:

If you want to utilize the call properties, it is recommended to make certain information dynamic on a call-by-call basis. While the foundation to use call properties is provided in the adapter library, it is not generally exposed all the way through to IAP workflow. As a result, you will need to make changes to allow for the "dynamic" information to be passed into the adapter methods.
- Adding a parameter to every method in the adapter.js. You can use a single parameter but it is often better to make it an object so it can be expanded in the future.
- Add the fields and values into the callProperties on the request object in the adapter.js.

adapter.js Example

getMyData(query, callProps, callback) {

....

const reqObj = {
  payload: { garbage: 'need since post' },
  uriPathVars: [groupId, deviceId],
  uriQuery: { name: 'anyname' }, 
  uriOptions: { page: 2 },
  addlHeaders: { audit: 'turnOn' }, 
  authData: {
    domain: domainVar
  },
  callProperties: callProps,
  filter: '[*name=doggie]'
};

Changes to the pronghorn.json File:

Because you are changing the method signature in the adapter.js, you will also need to make changes to allow for the "dynamic" information to be passed into the adapter methods in the pronghorn.json file.
- Adding the input into every method defined in the pronghorn.json file.

pronghorn.json Method Example

    {
      "name": "getMyData",
      "summary": "get my data from blah",
      "description": "get my data from blah",
      "input": [
        {
          "name": "query",
          "type": "object",
          "info": "object containing query fields",
          "required": false,
            "schema": {
                "title": "query",
                "type": "object"
            }
        },
        {
          "name": "callProps",
          "type": "object",
          "info": "dynamic properties for the call { stub: true, authentication: { username: user, password: pwd } }",
          "required": true,
            "schema": {
                "title": "callProps",
                "type": "object"
            }
        }
      ],
      "output": {
        "name": "result",
        "type": "object",
        "description": "A JSON Object containing status, code and the result"
      },
      "route": {
        "verb": "POST",
        "path": "/getMyData"
      },
      "roles": [
        "admin"
      ],
      "task": true
    },