Macro Integration Point

The macro integration point accepts the following request payload as POST to:

http://[hostName]:[portNumber]/[api-context-root]/<context-root>/macros

{
   "parameters":[{
    "name":"",
    "value":""  // multivalued parameters hold a comma separated list of values
     },{
    "name":"",
    "value":""
    }],
    "macroDefinitionCode":""
    "requestContext": {
      Resembles generic api GET response structure
      "id" : // Mandatory
    }
}

e.g. context for group client

{
   "requestContext":{
      "id" : "" //mandatory
      "code": "",
      "displayName": "",
      "groupAccountList": [{
        "id": "26551" }]}
}

NOTE:: The macro request context element must specify the *id* of the object, this is considered as referenced subject id for Macro History

The next steps depends on the Macro type - 1) Dynamic Logic, 2) Bulk Update, and 3) OIG Integration.

Dynamic Logic

System invokes dynamic logic of signature 'Macro' as specified by the macro definition. This dynamic logic takes in the parameters and context from the request and the object identified by the context id in the request (group client, group account, or group account product). Note that the parameter values are always interpreted as a string. A string containing commas will be converted to a list of strings.

To supply the right object to the logic, the system refers to 1) macro definition’s context setting and 2) context element within the request. Macro definition context setting specifies the object type - group client, group account or group account product.

The dynamic logic allows for modification of the (context)object e.g. update contact person details. The system returns success (201) and the following response when the dynamic logic execution starts.

Sample success response

201: Created

  "links":[{
      "href" : "Task URI",
      "rel" : "operator",
      "httpMethod" : "GET"
      },{
      "href" : "refers to macro history,
      "rel" : "monitor",
      "httpMethod" : "GET"
      }
    }]
}

In case of error in executing the dynamic logic for example, dynamic logic is not of right signature, the system may return one or more error messages along with appropriate http error code.

Dynamic logic based macros are recommended for only simple data manipulation requirements.

Bulk Update

The system starts bulk update activity.

The parameter list must contain all the parameters required for the bulk update activity. The system identifies the bulk update definition from the macro definition.

The response for such a macro contains an operator link with a reference to the underlying activity.

In case of failure in starting the activity, one or more error messages as given by the activity are returned.

Sample success response

201: Created

  "links":[{
      "href" : "Activity URI",
      "rel" : "operator",
      "httpMethod" : "GET"
      },{
      "href" : "refers to macro address,
      "rel" : "monitor",
      "httpMethod" : "GET"
      }
    }]
}

OIG Integration

The system starts OIG integration as specified by the property ohi.macro.{0}.endpoint. The system sends the macro request as-is along with the details of macro resource (rel-link subject) as the payload for OIG integration. It uses credentials and authentication method for credentialKey OIG_INTEGRATION_{macrocode} to invoke OIG integration.

Sample request payload created by the system to start the OIG integration

{
   "parameters":[{
    "name":"",
    "value":""  // multivalued parameters hold a comma separated list of values
     },{
    "name":"",
    "value":""
    }],
   "links": [{
      "href" : "refers to macro history",
      "rel" : "subject",
      "httpMethod" : "GET"
      }],
     "requestContext":
     {
      "id"
      "code": "",
      "displayName": "",
      "groupAccountList": [{
      "id": "26551" }]}
}

The response for such a macro contains an operator link with a reference to the underlying exchange.

Sample success response

201: Created

  "links":[{
      "href" : "Exchange URI",
      "rel" : "operator",
      "httpMethod" : "GET"
      },{
      "href" : "refers to macro history,
      "rel" : "monitor",
      "httpMethod" : "GET"
      }
    }]

}

In case of failure in starting the integration, one or more error messages as given by the integration are returned.

Messages

The integration point may return HTTP status codes as defined in Response Messages. If an error occurs, the appropriate HTTP status code (along with a payload containing the details of the error) gets returned .

The following operation specific error can occur:

Table 1. Messages

Code	Severity	Message Text
OHI-IP-MRDF-001	Fatal	Macro definition code is unknown
OHI-IP-MRDF-002	Fatal	Request context could not be parsed
OHI-IP-MRDF-003	Fatal	Request context must specify the id element

Access Restriction

To start a macro, the user must have access to 1) 'macro IP' and 2) to the macro itself. Specifying the access restriction grant of type 'Macro' on the macro definition restricts the access to macro.