SOAP Header needs IntegrationCode

[trepidity]

autotask_api/lib/autotask_api/client.rb

Line 29 in 934cb57

def create(xml)

AutoTask is requiring an IntegrationCode to be passed in the header. I implemented it, but I feel it's hacky. Would you have a suggestion on how to better implement?

Here's how I did it.

    def create(xml)
      savon_client.call :create, message: "<Entities>#{xml}</Entities>",
        attributes: { xmlns: NAMESPACE },
                      soap_header: {
                          'tns:AutotaskIntegrations' => {'tns:IntegrationCode' => ENV['IntegrationCode']}
                      }
    end

[scoop]

Do you have a reference to the documentation for that? Is this a recent change in one of the newer releases like 2018.1?

Is it only relevant for the create call? If not, we can apply it universally for the Savon client in the initialize method, by passing soap_header to Savon.client.

Other than that, I don't think the ENV approach is entirely hacky. I'd use a more unique name though, such as ENV['AUTOTASK_INTEGRATION_CODE'].

[trepidity]

It was added to the API December 31, 2017.

It's for all methods. The system doesn't fail when it's not present, yet.

Valid point on the naming.

Here's the email that AutoTask sent out.

Tracking identifiers for Autotask Web Services API integrations
Please note, this message is not applicable for Autotask customers with regards to their own custom or in-house created integrations. It applies to any developer partner that offers an integration into the Autotask channel. If your integration is listed on the Autotask website or in Autotask On-Line help, then please pay attention to this message.
This is the second notice of the tracking identifier. If you have already received and implemented your tracking identifier, then thank you and you don't need to read any further.

Autotask is implementing mandatory tracking identifiers for use with the Autotask Web Services API for integration developers selling or offering integrations into the Autotask channel. These tracking identifiers will validate that an integration is known, provide Autotask with more accurate API utilization metrics for planning and development, and assist Autotask Support in tracking activity when needed.

In order to access Autotask PSA customer databases, an integration must provide the identifier in the SOAP header of each Web Services call made to Autotask. Refer to code samples below. A unique, 26-character long string identifier will be assigned for each integration that a developer creates and operates.

You will be required to add tracking identifiers to your integrations by December 31, 2017. If you are unable to comply with the deadline, please acquire your tracking identifier now and provide us a timeframe that you will comply. We realize sometimes this needs to worked into a development release cycle so please work with us to keep communications and the transition smooth.

Most integration developers have one integration and will require only one tracking ID, but some will require multiple tracking identifiers. If an integration can be deployed on premise or in the cloud, the on-premise version should have a different tracking ID from the cloud version. Development, testing and production usage can all use the same tracking identifier.

How to request identifiers

To request a new tracking identifier, please email to integrations@autotask.com. The email must include the following information:

Integration Partner/Vendor name
Integration name
Technical support contact name, phone number, and email address (please do not use sales or general contact information)
Brief description of the integration
Whether the integration is cloud based, on-premise, or both or a hybrid of both.

A member of the Autotask Integrations Team will respond to the contact email address you include with your request and provide the tracking identifier or, if needed, request additional information.

Code Samples to implement

Sample SOAP Header with Integration ID (Tracking Identifier)

soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Header>
...
      <IntegrationCode>XPLOKMIJNUHBYXXXFCRDXESZWA</IntegrationCode>
...
</soap:Header>

Example of SOAP XML with a query on the Account entity:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <AutotaskIntegrations xmlns="http://autotask.net/ATWS/v1_5/">
      <IntegrationCode>XPLOKMIJNUHBYXXXFCRDXESZWA</IntegrationCode>
    </AutotaskIntegrations>
  </soap:Header>
  <soap:Body>
    <query xmlns="http://autotask.net/ATWS/v1_5/">
      <sXML><![CDATA[<queryxml><entity>Account</entity><query><condition><field>id<expression op="greaterthan">0</expression></field></condition></query></queryxml>]]></sXML>
    </query>
  </soap:Body>
</soap:Envelope>

[scoop]

That‘s gonna be interesting how they‘re planning to enforce it if in-house API calls aren‘t required to provide any integration codes 🤔

But yeah, given this background I’d add it to AutotaskAPI::Client.initialize and only add the header if ENV[‘AUTOTASK_INTEGRATION_CODE’] is present.