Authenticate with Panoply

This guide will teach you how to authenticate with Panoply. Panoply utilizes a form of authentication which is present within the body of the request.

HTTP Client

To configure the HTTP client from the dashboard, navigate to Configuration > HTTP Clients. On the overview page click on the button to create a new HTTP Client.

On the creation page, give the new HTTP client a easily identifiable name, in this example, the client will be named "Panoply". The description field will contain the value "Panoply HTTP Client".

Plugins

Under Plugins to use add three new plugins. The first plugin will be of the type "Add base URI to requests". The value for this plugin should be the URL for the Panoply host e.g.: https://www.mysdkhost/sdk-account-rand.

The second plugin that needs to be added is the Set request headers. This plugin will add the correct Content-Type header to the requests. To do so, add one new entry to the array of headers and give it the following key => value pair: Content-Type => application/x-www-form-urlencoded.

The final plugin should be the Add content length headers to requests plugin. This plugin requires no further configuration.

After this is configured, save the HTTP client.

HTTP Client Plugins

Environment variables

For this request, a few environment variables are required. Navigate to Configuration > Environment variables and add two new variables. For both variables it is advised to check the encrypted checkbox. First variable should have the name PANOPLY_API_KEY. The second variable should be named PANOPLY_API_SECRET. Save both variables.

Transformer

In order to set the correct values in the body and successfully authenticate with Panoply a generic transformer needs to be created. This transformer expects a node to be available with the key body. This body will then be encoded and used in the request.

Go to Configuration > Transformers and create a new transformer. Give the transformer configuration a name and description e.g.: "Add Panoply Authentication".

The prototype should be a Data transformer.

Basic setup

Then add the first transformer which will be a Value mapper. This first transformer will setup the payload node. This node can later be selected in the publisher as the output. Give the value mapper one mapper, the type of this mapper should be List: inherit from supplied data. Add one node to the array, the key should become payload and value should be cleared. The first transformer is now done.

First transformer

Add a second Value mapper transformer. This time add an accessor of the type Pattern accessor. The pattern for this accessor should be payload. Give the Value mapper a mapper of the type List: inherit from supplied data. Add the follow key => value pairs to the array:

  • 0 => Action=SendMessage
  • 1 => no value
  • 2 => MessageAttribute.1.Name=key
  • 3 => MessageAttribute.1.Value.DataType=String
  • 4 => no value
  • 5 => MessageAttribute.2.Name=secret
  • 6 => MessageAttribute.2.Value.DataType=String
  • 7 => no value
  • 8 => MessageAttribute.3.Name=sdk
  • 9 => MessageAttribute.3.Value.DataType=String
  • 10 => MessageAttribute.3.Value.StringValue=PKGNAME-SDKVERSION

In the tenth node replace the PKGNAME-SDKVERSION part with the services' version and name. And now the second transformer is done. This transformer set up a few basic values and prepared an array to write more information to along the way.

Second transformer

Add a third Value mapper transformer. Give it a Pattern accessor with the pattern payload.4. Add a List: inherit from supplied data mapper with the following key => value pairs:

  • 0 => MessageAttribute.1.Value.StringValue
  • 1 => ${PANOPLY_API_KEY}

Add another mapper to this transformer with List: Implode to string mapper. Under the Glue field, add the value =. This transformer took care of adding the API key to the request body. It combined the result of the new inherited list with an = character. The third transformer is now done.

Third transformer

Add a fourth Value mapper transformer. Give it a Pattern accessor for the seventh node in the payload array array, so payload.7. Add the List: inherit from supplied data mapper again with the following key => value pairs:

  • 0 => MessageAttribute.2.Value.StringValue
  • 1 => ${PANOPLY_API_SECRET}

Then add a List: Implode to string mapper with the same configuration from the previous transformer. So with the Glue field filled with only an = character. This transformer performed a similar job to the previous one, the only key difference is that this time, the PANOPLY_API_SECRET environment variable was added instead. The fourth transformer is now done.

Fourth transformer

For the fifth transformer create another Value mapper. Give it a Pattern accessor with the pattern payload.1. Add a List: inherit from supplied data mapper with the following key => value pairs:

  • 0 => MessageBody
  • 1 => no value

This transformer prepared the body encoding node.

Fifth transformer

Now create a sixth transformer of the type Move using a pattern. The pattern should select the node in which the actual content of the request exists, for this example that would be body. Then in the replacement field add payload.1.1. This transformer will move the content of the body to the empty payload node from the previous transformer.

Sixth transformer

Create the seventh transformer of the type Value mapper. Give it a Pattern accessor for the node of the body in the payload, so: payload.1.1. Then under mappers add two mappers, the first mapper will be of the type Json: Encode. The default values for this mapper are fine. The second mapper should be of the type URL: Encode. The second mapper does not expect any values.

In this transformer the content of the body received the correct encoding for the request.

Seventh transformer

In the eighth transformer the body will be merged with an = character. So it should be of the type Value mapper again. This time, the Pattern accessor should select the node payload.1. Add a List: Implode to string mapper with an = character as its' value.

Eighth transformer

In the ninth and final transformer will merge all fields into one URL string for the request. Add the Value mapper with a Pattern accessor and select the payload node. Then add the final mapper of the type List: Implode to string and use the & for the Glue field.

Ninth transformer

Now the transformer is finished and should be saved. This transformer can be used in any route to prepare the body of the request as long as the payload of the request is unencoded on the body node of the entity. The transformer should always be as low as possible in the stack e.g.: the last transformer added to the publisher of the route.

Outgoing configuration

Finally to create the outgoing configuration for this request, go to Configuration > Outgoing. Add a new configuration and give it a name and description. For the Publisher prototype select the HTTP Publisher, set the endpoint to which the request should call.

For example, if the call should be done to https://www.mysdkhost/sdk-account-rand/my-endpoint then the configured endpoint for this configuration should be /my-endpoint, because we configured the rest of the URL in the HTTP client. Select the appropriate Request method, e.g. post. For the Request parameters field keep the type on string and in the value field, set the value to &{payload}. Then select the HTTP Client which was configured at the start, so select Panoply. And finally add the transformer configuration that was created in the previous step so select Add Panoply Authentication under Configurations within the dropdown.

Outgoing configuration