User assignment

Admin users can add (assign) additional users to existing application subscriptions. User assignments can be done either through the AppDirect user interface or by calling the AppDirect account API.

The user assignment event notification allows vendors to receive notice (USER_ASSIGNMENT) when a user is assigned to an existing subscription. In order to allow users to be assigned to existing subscriptions, Developers must define a user assignment notification URL, such as http://example.com/assign?url= eventUrl, on the product's Edit integration page. AppDirect will call this URL when users are assigned to existing subscriptions. This URL must contain the eventUrl placeholder which will be replaced by the URL of the order event at runtime.

The Developer can use a URL for each event type or use a single URL to handle all event types. When an event occurs, AppDirect notifies the vendor by calling this URL, which is hosted by the vendor, and sends an eventUrl parameter. The eventUrl parameter identifies the location of an event, which the vendor can use to fetch information about that event. Upon notification, the vendor can perform an HTTP GET to the eventUrl to read an XML or JSON representation of the event.

The general flow for a user assignment event notification is as follows:

1. An admin assigns a user to an application from AppDirect.
2. AppDirect creates a uniquely identified USER_ASSIGNMENT event, which is persisted in the AppDirect marketplace. This event is uniquely identified by an eventUrl, such as https://www.acme-marketplace.com/api/integration/v1/events/d15bb36e-5fb5-11e0-8c3c-00262d2cda03.
3. AppDirect calls the configured User Assignment notification URL, passing the eventUrl as a parameter.
4. The vendor validates the OAuth-signature in the authorization header.
5. The vendor issues a request to read the USER_ASSIGNMENT event information using the token value. See Authorize inbound API requests (for separate credentials) Authorize inbound API requests (legacy) (for shared credentials) for information on how to securely retrieve event details.
   Vendors can specify the format of the response they receive from AppDirect. They can add Accept: application/json in their HTTP GET request to receive the response from AppDirect in JSON format. They can add Accept: application/xml in their HTTP GET request to receive the response from AppDirect in XML format. If vendors do not specify the content type, an XML payload will be returned.
6. This event contains the following elements:
   • type: The type of the event (USER_ASSIGNMENT in this case).
   • marketplace: Information about the AppDirect marketplace on which the event took place.
   • creator: The identity of the admin user who triggered the event.
   • payload: The event payload, containing the following elements:
     • user: The user who is being assigned.
     • attributes: An optional list of key/value pairs representing user attributes.
     • accountIdentifier: The account identifier provided by the application in the initial Subscription Order.
7. The vendor will add the retrieved user to their account system.
8. The vendor responds to the original call from AppDirect with the following attributes:
   • success: Which should be "true" or "false."
   • errorCode: If "success" is false, this must contain a valid error code, see Event error codes.
   • message: An optional message containing information about the result of the operation.

Example USER_ASSIGNMENT event notification

• JSON

{
    "type": "USER_ASSIGNMENT",
    "marketplace": {
      "baseUrl": "https://www.acme.com",
      "partner": "APPDIRECT"
    },
    "creator": {
      "email": "c734676b-40f6-4783-b4ee-e20d59bbf943",
      "firstName": "Another",
      "language": "en",
      "lastName": "User",
      "locale": "en-US",
      "openId": "https://www.acme.com/openid/id/7ac30510-c54c-45ca-9c2f-f4d6b3aa2c15",
      "uuid": "7ac30510-c54c-45ca-9c2f-f4d6b3aa2c15"
    },
    "payload": {
      "account": {
        "accountIdentifier": "199722",
        "status": "ACTIVE"
      },
      "user": {
        "email": "c734676b-40f6-4783-b4ee-e20d59bbf943",
        "firstName": "Another",
        "language": "en",
        "lastName": "User",
        "locale": "en-US",
        "openId": "https://www.acme.com/openid/id/7ac30510-c54c-45ca-9c2f-f4d6b3aa2c15",
        "uuid": "7ac30510-c54c-45ca-9c2f-f4d6b3aa2c15"
      }
    }
}

• XML

<?xml version="1.0" encoding="UTF-8" ?>
<event>
        <type>USER_ASSIGNMENT</type>
        <marketplace>
                <baseUrl>https://www.acme.com</baseUrl>
                <partner>APPDIRECT</partner>
        </marketplace>
        <creator>
                <email>c734676b-40f6-4783-b4ee-e20d59bbf943</email>
                <firstName>Another</firstName>
                <language>en</language>
                <lastName>User</lastName>
                <locale>en-US</locale>
                <openId>https://www.acme.com/openid/id/7ac30510-c54c-45ca-9c2f-f4d6b3aa2c15</openId>
                <uuid>7ac30510-c54c-45ca-9c2f-f4d6b3aa2c15</uuid>
        </creator>
        <payload>
                <account>
                        <accountIdentifier>199722</accountIdentifier>
                        <status>ACTIVE</status>
                </account>
                <user>
                        <email>c734676b-40f6-4783-b4ee-e20d59bbf943</email>
                        <firstName>Another</firstName>
                        <language>en</language>
                        <lastName>User</lastName>
                        <locale>en-US</locale>
                        <openId>https://www.acme.com/openid/id/7ac30510-c54c-45ca-9c2f-f4d6b3aa2c15</openId>
                        <uuid>7ac30510-c54c-45ca-9c2f-f4d6b3aa2c15</uuid>
                </user>
        </payload>
</event>