Partner Web Services ExportSubscriptions Service Manual

AUTODESK ExportSubscriptions Service Reference Manual 1

Partner Web Services

ExportSubscriptions

Service Manual

Version 1.0.13


Contents 1 Introduction ...................................................................................................................................... 6

1.1 Overview .................................................................................................................................... 6

1.2 Supporting Resources ............................................................................................................ 6

1.3 Intended Audience .................................................................................................................. 6

2 Service Overview ............................................................................................................................... 7

3 Service Endpoints ............................................................................................................................. 7

4 How it Works ..................................................................................................................................... 8

4.1 File Generation process .......................................................................................................... 8

4.1.2 Data Request ..................................................................................................................... 8

4.1.3 Status check and file download ................................................................................... 8

4.1.4 File decryption .................................................................................................................. 9

4.2 Process Flow for Partners ...................................................................................................... 9

4.3 Data Model & Relationships ................................................................................................. 11

4.3.1 Restrictions ...................................................................................................................... 11

5 Service Request & Response Schema ........................................................................................ 12

5.1 PostExportSubscriptions ...................................................................................................... 12

5.1.1 Request ............................................................................................................................. 12

5.1.2 Response .......................................................................................................................... 13

5.2 GetSubscriptionsExportJobSatus ...................................................................................... 14

5.2.1 Request ............................................................................................................................ 14

5.2.2 Response ........................................................................................................................... 15

6 Output file CSV file structure ....................................................................................................... 17

7 Sample Requests/Responses ...................................................................................................... 32

7.1 PostExportSubscriptions by start date ............................................................................ 32

7.2 PostExportSubscriptions by start and last modified dates ........................................ 32


7.3 GetExportSubscriptionsStatus ........................................................................................... 33

7.4 Error .......................................................................................................................................... 34

8 Formatting Standards ................................................................................................................... 36

9 Error Messages ............................................................................................................................... 37

9.1 HTTP Status Codes & Errors ................................................................................................ 37

9.2 400 Bad Request Errors ....................................................................................................... 38

Appendix A: OpenSSL configuration ................................................................................................. 39

Linux/Unix/MacOS ............................................................................................................................. 39

Windows ............................................................................................................................................... 39

Tables Table 1: Service Endpoints ...................................................................................................................... 7 Table 2: Process flow for Partners example .................................................................................... 10 Table 3: Universal Data Filters ............................................................................................................. 11 Table 4: Request ..................................................................................................................................... 13 Table 5: Detailed JSON Response Structure ................................................................................... 14 Table 6: Request ..................................................................................................................................... 14 Table 7: Detailed JSON Response Structure ................................................................................... 16 Table 8: Output CSV file structure ..................................................................................................... 30 Table 9: HTTP Status Codes & Errors ................................................................................................. 37 Table 10: 400 Bad Request Errors ...................................................................................................... 38


Revision History Version Date Author Comments 1.0.1 Oct 16, 2019 Jordi Gilabert • Initial version of the

GetSubscriptionsExport reference documentation

1.0.2 Oct 20, 2019 Jordi Gilabert • Removed document Draft status • Updated error codes in section 9

1.0.3 Oct 25, 2019 Jordi Gilabert • API name formally changed from GetSubscriptionDataBulk to GetSubscriptionsExport

1.0.4 Nov 13, 2019 Jordi Gilabert • Use of RFC 4180 for output CSV file is specified on sections 4.1.4 and 0

1.0.5 Nov 19, 2019 Jordi Gilabert • GetSubscriptionsExportJobStatus endpoint changed from “/v1/jobs/{id}” to “/v1/export/subscriptions/{id}” in section 3

• Error structure added to API Services responses in sections 5.1.2 and 5.2.2

• Changes in the response fields for GetSubscriptionsExport in section 5.1.2:

o “jobId” renamed to “id” o “transactionId” renamed to

“x-adsk-request-id” and moved to respose header

• Changes in the response fields for GetSubscriptionsExportJobStatus in section 5.2.2:

o “jobId” renamed to “id” o “transactionId” renamed to

“x-adsk-request-id” and moved to respose header

• Examples updated in section 7

1.0.6 Dec 16, 2019 Jordi Gilabert • Field ews.onboardingHealth.score added in Section 6

• endCustomer.contractManager.address2 and endCustomer.contractManager.address3 have been fixed in Section 6, where


before endCustomer.contractManager.address1 was present 3 times

1.0.7 Feb 19, 2020 Jordi Gilabert • Nurture Reseller information visibility updated in Table 8

1.0.8 Mar 9, 2020 Jordi Gilabert • Early Warning System (EWS) reduced data set by retiring low usage EWS attributes in Section 6

1.0.9 Apr 22, 2020 Jordi Gilabert • Added new output field “packSize” in Section 6

1.0.10 Jun 2, 2020 Jordi Gilabert • Added new output fields “licenseType”, “activationType” and “programType” in Section 6

1.0.11 Jun 30, 2020 Jordi Gilabert • API name changed from GetSubscriptionsExport to ExportSubscriptions

• GetSubscriptionsExportJobStatus changed to GetExportSubscriptionsStatus

• Added new output field “lastPurchaseDate” in Section 6

1.0.12 Jul 10, 2020 Jordi Gilabert • Updated return value for “switchType”, “switchYear” and “programType” fields in Section 6

1.0.13 Nov 4 2020 Jordi Gilabert • Field description updates on Section 6 for fields:

o Contract Term o Program Type o Parent Industry Group


1 Introduction

1.1 Overview

The Autodesk Partner Web Services platform is an automation solution for low-touch order placement by partners directly to Autodesk. This platform enables true B2B web service transactions between distribution partners and Autodesk.

For partners to effectively implement Autodesk web services, partner developers should be familiar with RESTful web services, OAuth, and the JSONdata-interchange format.

1.2 Supporting Resources

Autodesk Partner Developer Portal: The Autodesk Partner Developer Portal is a site for partner developers to build and test applications by subscribing to Autodesk Partner Web Services. The portal features a robust repository of service documentation, an ongoing conduit to the services to support partner teams, and a community to allow partner developers to share insights and information with each other. A partner administrator can invite and manage developersand keep track of all applications they create. Developers can learn and test services to help with application integration. For more information, please visit the Autodesk Partner Developer Portal.

Authentication API Documentation: The Authentication API Documentation is intended to help partner developers understand and use the OAuth 2.0 industry-standard protocol for authorization required to use Autodesk Partner Web Services. The documentation provides basic information on web service integration and examples of developing a typical application. For more information, please visit the Autodesk Partner Developer Portal for the latest version of the API Authentication Guide.

1.3 Intended Audience This guide is designed to teach architects, consultants, and developers about the Autodesk Partner Web Services platform, the onboarding process, and API implementation guidelines.


2 Service Overview

The ExportSubscriptions service is intended to:

• Provide subscription and customer information in bulk • Reduce the dependency on Partner Center for renewal reports, contract coverage

reports, accounts, Early Warning System information, and dashboards • Scale to meet the demands of Partner CRM data ingestion • Help forecast and prioritize upcoming renewals

GetSubscriptionData is an informational service designed to return subscription, product, opportunity, contract, partner, early warning system, and customer information for partner distributors and resellers. The service will return a subscription’s information when the requesting partner is either the sold to or reseller of record. The service requires a subscription start date but additional last modified date is also available to select a smaller subset of subscription information.

Disclaimer: Although the service is similar to the reports available in Autodesk’s Partner Center and BI dashboards, the data may not always align between the two experiences as the reports and dashboards require an 8-24 hour lead time to properly reflect the latest information. In addition, certain features and subscription information were strategically added or removed due to new business models and performance.

3 Service Endpoints

Environment URL PostExportSubscriptions Staging https://enterprise-api-stg.autodesk.com/v1/export/subscriptions Production https://enterprise-api.autodesk.com/v1/export/subscriptions GetExportSubscriptionsStatus Staging https://enterprise-api-stg.autodesk.com/v1/export/subscriptions/{id} Production https://enterprise-api.autodesk.com/v1/export/subscriptions/{id}

Table 1: Service Endpoints


4 How it Works

4.1 File Generation process

1. Perform the Data request by sending the Start and Last Modified dates 2. Store the password and jobID returned from the POST request 3. Poll the jobID endpoint which will get redirected to the file when ready 4. Download the file 5. Decrypt the file using openssl and the password from step 2 6. Unzip the file using any standard unzip utility 7. Export the data contained in the CSV file into Partner’s CRM/Database/System

4.1.2 Data Request

The POST request will be processed asynchronously and will queue the request and return the response on the queue status check once it is completed.

4.1.3 Status check and file download

1. Check Queue while processing with GET handling 200-HTTP response code 2. Check Queue while processing returns completed processing with a 303-HTTP response

code and a new Location Header


3. Get the processed file by doing a GET on the returned location. Note this will be a signed URL with a short duration span to get it. In case it is expired you will have to repeat the step above to get a new non expired URL.

4.1.4 File decryption

For security and data protection reasons, the created file is encrypted and only the authorized Partner will have access to the contained information. To decrypt the downloaded file, the password returned in the response of PostExportSubscriptions (section 4.1.2) will be used. Please use the following commands based on your system’s OS:

• Linux/Unix/MacOS

openssl enc -aes-256-cbc -md sha512 -d -in {datafile}.csv.zip.enc -out {datafile}.csv.zip -k {password}

• Windows

openssl enc -aes-256-cbc -md sha512 -d -in C:\Users\user1\Downloads\{datafile}.csv.zip.enc -out C:\Users\user1\Downloads\{datafile}.csv.zip -k {password}

Once the file has been decrypted, any standard unzip utility can be used to obtain the resulting CSV file.

Resulting CSV file will follow RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files

4.2 Process Flow for Partners

ExportSubscriptions, unlike the ad-hoc version, will only support startDateSince as the main driver for the query. This same startDateSince value should be used for all delta loads going forward with a change in lastModifiedSince value.

The below example illustrates the suggested process flow to allow Partners update their records in a daily basis:


• First request made on 2019-01-01T00:00:00Z - with startDateSince value of 2000-01-01T00:00:00Z and lastModifiedSince if not passed will be same as 2000-01-01T00:00:00Z. Implies a full batch load of the data.

• Second request to refresh the previously recorded batch data is made on 2019-01-02T00:00:00Z should be with the same startDateSince value of 2000-01-01T00:00:00Z and should have lastModifiedSince value of 2019-01-01T00:00:00Z which will return only the records that have been modified since your last batch load request.

• Third and subsequent request should be incremental refresh similar to above, for instance, on 2019-01-07T00:00:00Z should be with the same startDateSince value of 2000-01-01T00:00:00Z and should have lastModifiedSince value of 2019-01-02T00:00:00Z

Request# Request Date startDateSince lastModifiedDate Description 1 2019-01-01 2018-01-01 none/default First load 2 2019-01-02 2018-01-01 2019-01-01 Second delta 3 2019-01-07 2018-01-01 2019-01-02 Third delta

Table 2: Process flow for Partners example


4.3 Data Model & Relationships

The service request header’s CSN determines what subscription information is available to the requesting partner. The service will filter subscriptions where the requesting partner is an associated entity.

4.3.1 Restrictions

The following are restrictions for the ExportSubscriptions service. These restrictions cannot be changed. If subscription information that meets these restrictions are required, Autodesk suggests using the latest version of the GetLicense service.

Filter Value(s) Not Included Product Asset Status

Registered Upgraded, Inactive products/assets

Usage Type Commercial Product Not for Resale, Education, etc. Parent Collection Industry Collection, AutoCAD

with Specialized Toolsets, future bundles

Individual products that constitute the collection

Table 3: Universal Data Filters


5 Service Request & Response Schema

5.1 PostExportSubscriptions

5.1.1 Request

The following information represents the request schema for the PostExportSubscriptions service. As this service is a RESTful web service, metadata sent in the HTTP header is required. This service has to be invoked using “POST” operations.

Please note that elements in bold denote objects and arrays.

Filter Cardinality Description Data Type Length Example startDateSince M A subscription start date to be used to query

this data. The service returns all subscriptions that began since the specified start date from. A startDateSince value is always required. Anything prior to 1980-01-01. will be considered as full data load.

String - ISO 8601 Date Format

22 • With Timezone 2019-06-25T15:18:54+07:00 • UTC 2019-06-25T15:18:54Z

lastModifiedSince O Date time stamp value for the delta data to pull. Returned records will have a lastModified value greater than the value passed here. It will default to startDateSince if no value is passed, this implies a full batch load of all the data since start date.

String - ISO 8601 Date Format

22 • With Timezone 2019-06-25T15:18:54+07:00 • UTC 2019-06-25T15:18:54Z


Table 4: Request

5.1.2 Response

The following information represents the response schema for the PostExportSubscriptions service.


Element Cardinality Description / Condition Data Type Length Example status M Indicates the status of the web

service call. Not returned in the event of an error.

String 10 “processing”

id M Job id needed to invoke the GetExportSubscriptionsStatus service. Not returned in the event of an error.

String – UUID v4 Format

36 "8da54694-1511-44dc-8f9e-b512aa9404fc"

password M Password needed to decrypt the resulting output file. Not returned in the event of an error.

String 48 "N2FkYTcyZmEtM2JmMC00NWFlLWJmZWEtMWMxMDg2NzI0YWI1"

x-adsk-request-id M The unique identifier of the web service call. This element is sent in the response header


36 “6ba98179-a24f-4b50-ab16-ddf115391486”


error O Error when processing the event, if any.

JSON Object - -

{ - - - - -

code O Error code associated with error message. Please check section 9 for error codes and descriptions.

String 5 “43001”

message O Human readable message explaining error. Please check section 9 for error codes and descriptions.

String 50 “Enter a valid startDateSince”

} - - - - -

Table 5: Detailed JSON Response Structure

5.2 GetSubscriptionsExportJobSatus

5.2.1 Request

The following information represents the request schema for the GetExportSubscriptionsStatus service. As this service is a RESTful web service, metadata sent in the HTTP header is required. This service has to be invoked using “GET” operations.


Filter Cardinality Description Data Type Length Example jobId M Id returned in PostExportSubscriptions

response. String – UUID v4 Format

36 "8da54694-1511-44dc-8f9e-b512aa9404fc"

Table 6: Request


5.2.2 Response

The following information represents the response schema for the GetExportSubscriptionsStatus service.


Element Cardinality Description / Condition Data Type Length Example status M Indicates status of the web

service call. Not returned in the event of an error.

String 10 “processing”

id M The unique identifier of the web service call. Not returned in the event of an error.


36 “8da54694-1511-44dc-8f9e-b512aa9404fc”

x-adsk-request-id M The unique identifier of the web service call. This element is sent in the response header


36 “6ba98179-a24f-4b50-ab16-ddf115391486”

error O Error when processing the event, if any.

JSON Object - -

{ - - - - -

code O Error code associated with error message. Please check section 9 for error codes and descriptions.

String 5 “43003”

message O Human readable message explaining error.

String 50 “Job id is required”


Please check section 9 for error codes and descriptions.

} - - - - -

Table 7: Detailed JSON Response Structure

Once the job is completed, the service will respond with a 303 HTTP Code, redirecting automatically to the file’s remote location.


6 Output file CSV file structure

In order to adapt the Output CSV file as much as possible to the JSON Response obtained with the GetSubscriptionData ad-hoc version (https://partner.developer-stg.autodesk.com/products/#subsdata-documents), the outfile file exports the same information as in the ad-hoc version and the headers use indexed fieldnames (i.e. parent.child) to replicate the JSON Response structure.

Field (CSV Header) Description Values Example Asset information

subscriptionReferenceNumber The serial number or subscription ID of the subscription.

“712-10049860”

productLanguage The language version of the product the customer is subscribed to.

“Non-Language Specific”

productStatus The status of the product the customer is subscribed to. At this point, service only returns assets with the following status:

Registered “Registered”

subscriptionType The type of subscription or offering the customer purchased.

Renewable Subscription Auto-Renew Subscription Renewable Maintenance

“Renewable Subscription”

groupName The group the subscription belongs to as specified by the reseller or sold to.

“Project ABC”

quantity The expected order quantity when renewing a subscription.

1

seats The number of seats purchased by the customer.

1


packSize Number of seats per SKU unit.

25

subscriptionStatus Subscription’s status. Active Inactive Expired

“Active”

lastPurchaseDate Date when the customer registered their subscription.

“2017-05-05”

startDate The date a subscription first began.

“2017-05-05”

endDate The date a subscription will expire if it will not be renewed or was cancelled.

If it is an active auto-renew subscription, the service will return “Auto-Renewing Subscription.”

“2018-05-04” OR “Auto-Renewing Subscription”

description The description and language of the product the customer is subscribed to.

Language Specific”

productLine The description of the product the customer is subscribed to.

“Architecture Engineering Construction Collection”

productLineCode The product line code of the product the customer is subscribed to.

“AECCOL”

solutionDivision The possible industry segment the product is meant for use.

AEC M&E MFG PSEB Programs ANIM

“AEC”

release The release version of the product the customer is subscribed to.

Release Year IC for Industry Collections AD for AutoCAD including Specialized Toolsets Cloud for Autodesk cloud subscriptions.

“2018”


deployment The license type of the product the customer is subscribed to.

S for Standalone N for Network

“S”

licensingModel A license model is a collection of rules that govern the response to a License Authorization Request.

TERM EFLEX TFLEX MFLEX

“TERM”

subscriptionLevel The subscription support level purchased by the end customer.

Platinum Gold Silver Bronze

“Gold”

switchType Switch Type indicates whether the subscription was exchanged, forfeited, or purchased via an Autodesk “switch” program.

M2S – Maintenance to Subscription (MTC to M2S or MTC to M2S Y4) M2SMU – M2S Multi-user Trade-in (M2S MUS to M2S SUS) M2SY4 – M2S MU May 2020+ Trade-in (M2S Y4 MUS to M2S SUS) MU – Multi-user Trade-in (MUS to SUS) MTC – Network Trade-in (MTC MUS to SUS)

“SWR”

switchYear Switch Year indicates the year a customer switched to subscription under the Maintenance to Subscription program. The switch year schedule anniversary date is 5/7.

FY18 – Between May/7/2017 and May/6/2018 FY19 – Between May/7/2018 and May/6/2019 FY20 – Between May/7/2019 and May/6/2020 FY21+ – Grater than May/6/2020

“FY19”

opportunityNumber The renewal opportunity number that can be used to renew the subscription.

“A-1234567”


licenseType Defines the type of license being sold.

Crossgrade when a customer upgrades to a different product Migration when a product migrates from another product New when is a brand new seat Upgrade when is a new release of a product the customer owns

“New”

activationType Determines how a subscription is activated.

Sign On for a Pelican-fulfilled subscription Serial Number for a classically-fulfilled subscription

“Sign On”

programType Describes the performance obligations for the product and service components within our Offerings. For upgraded assets, field may return NULL. Switch Type and Switch Year can be used instead.

M2S – Switched from Maintenance MY4 – Switched From Maintenance May 2020+ SU1 – M2S Multi-user 2:1 Trade-in SU2 – Multi-user 2:1 Trade-in SU3 – M2S MU May 2020+ 2:1 Trade-in SU4 – Network 2:1 Trade-in SU5 – M2S Multi-user 1:1 Trade-in SU6 – Multi-user 1:1 Trade-in SU7 – M2S MU May 2020+ 1:1 Trade-in SU8 – Network 1:1 Trade-in UP – User Pack UPA – User Pack Add-on

“M2S”

Contract information

contract.number The number of the contract that defines the licenses purchased with Maintenance Subscription, Desktop Subscription or Cloud Service Subscription and the associated benefits as defined in the Autodesk

“110009999999”


Subscription Program offering.

contract.startDate The original start date of the contract.

“2017-05-05”

contract.endDate The current end date of the contract. If it is an active auto-renew contract, the service will return “Auto-Renewing Contract.”

“2018-05-04” OR “Auto-Renewing Contract”

contract.term The contract term of the service contract and all subscriptions associated to the contract. Field will be NULL for Maintenance contracts

Monthly Quarterly Annual 2-Year 3-Year

“Annual”

contract.billingBehavior The billing behavior of the service contract.

Renewable Auto-Renew

“Renewable”

contract.subType The sub-type can indicate the type of contract, customer segment, or support level granted for the service contract.

Education Global NFR Per Incident Subscription Platinum Up & Ready Partner Support End Customer Support ADN Silver/Gold

“Silver/Gold”

contract.renewalCounter The renewal counter indicates the number of

“2”


times the service contract was renewed.

Early Warning System information

Adoption Health information

ews.adoptionHealth.currentMonth * The Adoption Health Usage Spectrum that enables insights into customer usage from Day 90 through contract expiration to help identify expansion opportunities and at-risk accounts.

This field will return Blank value due to low usage EWS attribute.

“Stable high”

ews.adoptionHealth.bimonthly1 * Adoption Health 1 month 12th day adoption health





















Onboarding Health information


ews.onboardingHealth.health * The Onboarding Health focuses on the first 90 days of the subscription term and measures activities that lead to successful onboarding or time-to-value of purchased subscriptions. These values are calculated daily for the first 90 days of the contract.


“Good”

ews.onboardingHealth.score * The Onboarding Health score where a higher score indicates better health.


ews.onboardingHealth.accessDriver * The Access Driver measures the customers progress in activating products & assigning users through Autodesk Account


ews.onboardingHealth.discoveryDriver * The Discovery Driver measures interactions with e-mails and other communications from Autodesk.


ews.onboardingHealth.productUtilizationScoreDriver * The Product Utilization Score Driver indicates whether the Customer is starting to use their product and cloud services in the first 90 days following the start of the contract.



ews.onboardingHealth.supportDriver * The Support Driver measures relevant support cases opened with Autodesk's technical support team.


Retention Health information

ews.retentionHealth.score The Retention Score is the statistical probability of renewal. The lower the number, the higher the renewal risk.

"0.63"

ews.retentionHealth.riskBand Retention Risk Band is the overall summary of the renewal risk for the subscription’s contract.

Very High Risk High Risk Medium Risk Low Risk Very Low Risk

“Very Low”

ews.retentionHealth.customerProfileScoreDriver * Customer Profile Driver measures the influence on retention that comes from a customer's profile information.


ews.retentionHealth.productUtilizationDriver * Product Utilization Driver measures the influence that product usage has on the overall potential for a future renewal.


ews.retentionHealth.productProfileScoreDriver * Product Profile Driver measures the impact a product (or mix of products) has on the renewal of a subscription.


ews.retentionHealth.subscriptionEngagementScoreDriver *

Subscription Engagement Driver measures engagement a customer has with the benefits of a subscription.



Accounts information

Sold-To information

accounts.soldTo.csn Sold To account CSN (Customer Specific Number)

“5122424123”

accounts.soldTo.name Sold To account name

“Distributor Ltd”

Reseller information

accounts.reseller.csn Reseller account CSN (Customer Specific Number)

“5122424540”

accounts.reseller.name Reseller account name

“Reseller Ltd”

accounts.reseller.localLanguageName Reseller account name in local language

“Reseller Limited”

accounts.reseller.resellerType The classification of a reseller account based on its industry or its financial relationship with Autodesk.

A.D.N. Distributor End Customer Government Internal ISV Build ISV Bundle Reseller Strategic Account Training Center Vendor

“Reseller”

accounts.reseller.address1 Reseller account address line 1

“111 McInnis Parkway”


“2nd floor”


“Office 5113B”

accounts.reseller.city Reseller account city

“San Rafael”

accounts.reseller.stateProvince Reseller account state or province code

“CA”

accounts.reseller.postalCode Reseller account postal code

“941007”

accounts.reseller.country Reseller account country

“US”


Nurture Reseller information Nurture Reseller information is only populated when an opportunity is open for that subscription.

accounts.nurtureReseller.csn Nurture reseller CSN (Customer Specific Number)

“5122424540”

accounts.nurtureReseller.name Nurture reseller account name

“Reseller Ltd”

accounts.nurtureReseller.lockdate The lock date for setting the final nurture reseller during the subscription renewal period.

“2017-05-05T00:00:00Z”

accounts.nurtureReseller.nurtureDiscountEligibility The flag identifying whether the nurture reseller is eligible for a nurture discount from Autodesk.

"TRUE"

End Customer information

End Customer Account information

endCustomer.account.endCustomerCsn End customer account CSN (Customer Specific Number)

“5125009360”

endCustomer.account.name End customer account name

“Autodesk Inc”

endCustomer.account.type The classification of an end customer account based on its industry or its financial relationship with Autodesk.

A.D.N. Distributor End Customer Government Internal ISV Build ISV Bundle Reseller Strategic Account Training Center Vendor

“End Customer”

endCustomer.account.address1 End customer account address line 1



“2nd floor”



“Office 5113B”

endCustomer.account.city End customer account city

“San Rafael”

endCustomer.account.stateProvince End customer account state or province code

“CA”

endCustomer.account.postalCode End customer account postal code

“941007”

endCustomer.account.country End Customer account country

“US”

endCustomer.account.namedAccountFlag End Customer named account flag indicating if the end customer is a major or industry targeted account.

TRUE

endCustomer.account.namedAccountGroup Named Account Group if applicable

Emerging Strategic Account ITA Emerging Strategic Account MJA Industry Target Account Major Account Major Account Federal Major Account Global Midmarket Non Managed GP Protected

“Major Account”

endCustomer.account.parentIndustryGroup The lead Industry Group for each Parent company. This field may be NULL. Suggested to retrieve the value from GetAccount or ExportAccounts APIs

“AEC”

endCustomer.account.parentIndustrySegment The lead Industry Segment for each Parent company.

“Construction Services”

Contract Manager information

endCustomer.contractManager.first Contract manager first name

“Mike”

endCustomer.contractManager.last Contract manager last name

“Johnson”


endCustomer.contractManager.email Contract manager email

“'[email protected]'“

endCustomer.contractManager.address1 Contract manager address line 1



“2nd floor”


“Office 5113B”

endCustomer.contractManager.city Contract manager city

“San Rafael”

endCustomer.contractManager.stateProvince Contract manager state or province code

“CA”

endCustomer.contractManager.postalCode Contract manager postal code

“94107”

endCustomer.contractManager.country Contract manager country

“US”

endCustomer.contractManager.phone Contract manager phone number

“925-111-0000”

endCustomer.contractManager.fax Contract manager fax number

“925-111-0000”

endCustomer.contractManager.status The status of the contract manager with regards to their associated account.

Active Inactive Not at company Deceased

“Active”

endCustomer.contractManager.portalRegistration Contract Manager portal registration status

Active Inactive

“Active”

endCustomer.contractManager.doNotCall Contract Manager call preference

"FALSE"

endCustomer.contractManager.doNotEmail Contract Manager email preference

"FALSE"

endCustomer.contractManager.doNotMail Contract Manager mail preference

"TRUE"

Software Coordinator information

endCustomer.softwareCoordinator.first Software coordinator first name

“Mike”


endCustomer.softwareCoordinator.last Software coordinator last name

“Johnson”

endCustomer.softwareCoordinator.email Software coordinator email

“[email protected]”

endCustomer.softwareCoordinator.address1 Software coordinator address line 1



“2nd floor”


“Office 5113B”

endCustomer.softwareCoordinator.city Software coordinator city

“San Rafael”

endCustomer.softwareCoordinator.stateProvince Software coordinator state or province code

“CA”

endCustomer.softwareCoordinator.postalCode Software coordinator postal code

“94107”

endCustomer.softwareCoordinator.country Software coordinator country

“US”

endCustomer.softwareCoordinator.phone Software coordinator phone number

“925-111-0000”

endCustomer.softwareCoordinator.fax Software coordinator fax number

“925-111-0000”

endCustomer.softwareCoordinator.status The status of the software coordinator with regards to their associated account.

Active Inactive

“Active”

endCustomer.softwareCoordinator.portalRegistration Software Coordinator portal registration status

Active Inactive

“Active”

endCustomer.softwareCoordinator.doNotCall Software Coordinator call preference

“FALSE”

endCustomer.softwareCoordinator.doNotEmail Software Coordinator email preference

“FALSE”

endCustomer.softwareCoordinator.doNotMail Software Coordinator physical mail preference

“TRUE”

Table 8: Output CSV file structure


* note: This field will return a blank value as it is retiring due to low usage.


7 Sample Requests/Responses

The following information are sample requests and responses to be used as reference.

7.1 PostExportSubscriptions by start date

Request

POST /v1/export/subscriptions startDateSince=2019-01-01

Response

HTTP/1.1 202 Accepted Content-Type: application/json Date: Tue, 19 Nov 2019 09:24:24 GMT Location: /v1/export/subscriptions/fc44966c-e419-46e3-a904-46a96132927f x-adsk-request-id: 9fa90781-a95b-4dcd-a334-ddb1b49ebd4e x-amz-apigw-id: DZkvSHRVPHcFhcw= x-amzn-RequestId: a749f3de-1374-413a-92ca-65843814d281 X-Amzn-Trace-Id: Root=1-5dd3b4c8-c5cee6a8d93be32d225cff09;Sampled=0 Content-Length: 129 Connection: keep-alive { "id": "fc44966c-e419-46e3-a904-46a96132927f", "status": "processing", "password": "MjI5ZGI2NjYtZWZhNi00MmI1LWFlNjUtODFlODRkOTY2YmU2" }

7.2 PostExportSubscriptions by start and last modified dates

Request

POST /v1/export/subscriptions startDateSince=2019-01-01&lastModifiedSince=2019-10-06


Response

HTTP/1.1 202 Accepted Content-Type: application/json Date: Tue, 19 Nov 2019 09:25:58 GMT Location: /v1/export/subscriptions/88be7456-bb8a-4235-a4ff-d7bd99d1cbae x-adsk-request-id: 476cee5c-d673-4414-a462-afb625e9cab9 x-amz-apigw-id: DZk99Er5vHcFnxA= x-amzn-RequestId: 8397448f-1ac8-4c76-90ef-9127a2542393 X-Amzn-Trace-Id: Root=1-5dd3b526-48580180142bc51654729f02;Sampled=0 Content-Length: 129 Connection: keep-alive { "id": "88be7456-bb8a-4235-a4ff-d7bd99d1cbae", "status": "processing", "password": "OGQ2Y2ExOTMtNzFjZS00NDBhLWIyNjItNDI4ZDAxNGI2N2E4" }

7.3 GetExportSubscriptionsStatus

Request

GET /v1/export/subscriptions/d8d4d4fb-5e45-4708-9f91-034955db6cad

Response if job has not finished

HTTP/1.1 200 OK Content-Type: application/json Date: Tue, 19 Nov 2019 09:28:05 GMT x-adsk-request-id: c0ccd370-f79e-4406-b9ae-33366aee461d x-amz-apigw-id: DZlR3HHxPHcFawg= x-amzn-RequestId: 36d45c98-c404-42a2-9b3e-c811a131cffb X-Amzn-Trace-Id: Root=1-5dd3b5a5-720277a883233f1030a65984;Sampled=0 Content-Length: 67 Connection: keep-alive { "id": "d8d4d4fb-5e45-4708-9f91-034955db6cad", "status": "processing" }


Response if job has finished

HTTP/1.1 303 See Other Content-Type: application/json Date: Tue, 19 Nov 2019 09:28:20 GMT Location: https://pws-subs-export-stg-us-west-2.s3.us-west-2.amazonaws.com/5070055142/d8d4d4fb-5e45-4708-9f91-034955db6cad.csv.zip.enc?AWSAccessKeyId=ASIAVPINZCSCSYEFKXL3&Expires=1574156000&Signature=dj%2Fao7Aty12Pq6n%2FNDw6bxYc1Ew%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEJL%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLXdlc3QtMiJHMEUCIQDfyMxk6F8O5SvQ%2F1T0hbAqQ0IbmFZd1VFo%2FNpYLs0lsQIgD83N450njyoaE4vtD96C4HPVQEkGwG6FysY2CvH9H7Iq4wEIuv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARACGgwzNzYzNzU0MTU5NDEiDPIv%2FpOK%2Fd%2B22%2FrDyyq3AUlga6Dx1i5WOh1cxSIGnRfid9JbiYXOjnI4HmwsC78OEUdhutMmOG5MVFQeC%2Bv%2Fu881dO9YNUzzpfFcv4i0XCNTwhJADdm3Mqbkik3mor0Ckqz%2FiH7zPyyppGHNgtB36UI0BZP70F5y%2FJotxTsbz0Y%2FhvODLUuFV14E3Hln8uxuqbg4dN9gdI8cmGrrivs63rhF1KsLug9DLujX%2BE8V%2BUnJcImR1alk4Jy7osLqEP%2BSNcPyCmUiyDCC587uBTrgAS07iFL6N4L%2FyxgABvwNwYf9vJamY8g8TXhT2MxoB%2FB8BA%2FaaLaPO%2FRwoN4fQtDdfJkt7yxlMfPvX2rQsPSjD0S9rbH%2FU0uontSth2oOokdVpzRZSV7FOTCWcP2hA1CixnysLLPkPRQWIT3akxr4fg7A3BrpvRk4isMdXm0P2XAXUqYlN3p%2BhRlf%2BqGRNbvLcmNG%2FfQZy6%2B9meTDs7bnlyjx87rc0nvC4kEe8qaGFSIW9%2FHphB2ISNAasxNFi6q65RINY0zJerhX%2FBryqnskQdiVpeYoM%2FvjC0pQNKG3WvMc x-adsk-request-id: d4b51dd0-9619-407c-9971-4a71327b51ee x-amz-apigw-id: DZlUPFQ-PHcFrYQ= x-amzn-RequestId: 5b194221-c6a5-4c66-9dd7-2554d8dfd166 X-Amzn-Trace-Id: Root=1-5dd3b5b4-f46d62b6bdcf59a824891e2e;Sampled=0 Content-Length: 0 Connection: keep-alive

7.4 Error

PostExportSubscriptions

The following is an example of a GetSubscriptionBulk 400 bad request due to a missing start date.

HTTP/1.1 400 Bad Request Content-Type: application/json Date: Tue, 19 Nov 2019 09:31:23 GMT x-adsk-request-id: 384b929d-4f33-43c9-b7ca-0082ddc1f227 x-amz-apigw-id: DZlwrFMxPHcFZHw= x-amzn-RequestId: 92be2318-9dda-4c1d-b384-a66828eb4e98 X-Amzn-Trace-Id: Root=1-5dd3b66a-aea6015a24a59a9289b7ceca;Sampled=0 Content-Length: 67 Connection: keep-alive


{ "error": { "code": "43001", "message": "Enter a valid startDateSince" } }

GetExportSubscriptionsStatus

The following is an example of a GetSubscriptionBulk job status 404 bad request due to a wrong job id.

HTTP/1.1 400 Bad Request Content-Type: application/json Date: Tue, 19 Nov 2019 09:32:46 GMT x-adsk-request-id: 7b226638-94b2-4b68-b295-42d13d107533 x-amz-apigw-id: DZl9tGiXvHcFkLg= x-amzn-RequestId: 1e036bd7-e0cb-4cba-8bf1-6c3329c18913 X-Amzn-Trace-Id: Root=1-5dd3b6be-0689f032a5d615108ee912c0;Sampled=0 Content-Length: 58 Connection: keep-alive { "error": { "code": "43004", "message": "Job id is not valid" } }


8 Formatting Standards

UUID v4 – Unique, randomly generated string

https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_.28random.29

ISO 8601 – YYYY-MM-DD date format

http://www.iso.org/iso/home/standards/iso8601.htm

ISO 639-1 – Two letter language code

http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=22109

ISO 3166-1 alpha-2 format – two letter country code form

http://www.iso.org/iso/country_codes

RFC 1480 – Common Format and MIME Type for Comma-Separated Values (CSV) Files

https://tools.ietf.org/html/rfc4180


9 Error Messages

9.1 HTTP Status Codes & Errors

The following are all known HTTP status codes, error codes, and messages returned by the service due to a failure to authenticate, bad request, or exceeding maximum traffic allowed by the service.

HTTP Status Code Error Code Message 401 – Unauthorized 41001 Invalid access token 401 – Unauthorized 41002 Invalid CSN 401 – Unauthorized 41003 Invalid Signature 400 – Bad Request 41004 Invalid Timestamp 400 – Bad Request 41005 Missing access token 400 – Bad Request 41006 Missing signature 400 – Bad Request 41007 Missing timestamp 429 – Too Many Requests 41010 Quota limit violation 429 – Too Many Requests 41011 Spike arrest violation 400 – Bad Request 41012 Method not supported 504 – Gateway timeout 41013 Service request timeout

Table 9: HTTP Status Codes & Errors


9.2 400 Bad Request Errors

The following are all error codes, messages, and the reason for error returned when the service produces a 400 Bad Request or 500 Internal Server Error response.

Error Code Error Message Error Description PostExportSubscriptions 43001 Enter a valid <filter> Blueprint validation for filters. 43002 <filter> filter is required startDateSince has not been

passed in the web service request.

GetExportSubscriptionsStatus 43003 Job id is required Job id has not been passed in the

web service request. 43004 Job id is not valid jobID was not populated or does

not exist. 50001 Job processing error Application is unable to fetch the

job id from the dynamo DB. 50100 Internal server error Dynamo DB is resulting an error

response or queuing job results an error.

Table 10: 400 Bad Request Errors


Appendix A: OpenSSL configuration

Linux/Unix/MacOS

Most Linux based systems will have open SSL installed. Follow these steps to verify if OpenSSL is installed:

1. Open a shell window

Openssl version

2. Type the below command and hit enter 3. Version should be 1.1.0 or later

OpenSSL 1.1.0k 28 May 2019

Windows

The following steps are required in order to run openssl on windows:

1. Navigate to https://indy.fulgan.com/SSL/ a. Select the appropriate download for your windows operating system

i. For Windows 7 and up use versions with *-x64_86-win64.zip ii. For older versions of Windows *-i386-win32.zip

2. Unzip the file in the directory of your choosing (In this example we unzipped into the Downloads directory)

3. Verify that the contents of the unzipped file. You should see the following files.


4. Verify the installation (Note: In this example we downloaded and unzipped the contents to the Downloads directory. Your location may differ)

a. Open a new Command Prompt b. Navigate to the directory you unzipped

cd C:\{path_to_openssl}\openssl-1.0.2q-x64_86-win64>

c. Start OpenSSL

C:\Users\user1> C:\Users\user1> cd C:\{path_to_openssl}\openssl-1.0.2q-x64_86-win64> C:\{path_to_openssl}\openssl-1.0.2q-x64_86-win64>openssl WARNING: can't open config file: /usr/local/ssl/openssl.cnf

d. Check the OpenSSL version that is installed

OpenSSL> version OpenSSL 1.0.2q 20 Nov 2018 OpenSSL>

Documents

Partner Web Services ExportSubscriptions Service Manual