PWS GetInsightMetrics Service Reference Manual v1.0

Autodesk Partner WebServices

GetInsightsMetrics Service Reference Manual

Version 1.0.1

GetInsightsMetrics Service Reference Manual Contents • i

Revision History Version Date Author Comments 1.0.1 Mar 24, 2021 Jordi Gilabert Initial version of the document

GetInsightsMetrics Service Reference Manual Contents • ii

Contents Introduction 4

Overview ...................................................................................................................................... 4 Supporting Resources .............................................................................................................. 4 Intended Audience ................................................................................................................... 4

Service Overview 5

Service Purpose ......................................................................................................................... 5 EWS Insights Metrics ..................................................................................................... 5 Goals .................................................................................................................................. 5 Coverage ........................................................................................................................... 5 Limitations ........................................................................................................................ 6 Product Pool ..................................................................................................................... 7 Solution for Limitation .................................................................................................. 7

Service Endpoints 8

Staging ......................................................................................................................................... 8 Production .................................................................................................................................. 8

Service Request & Response 9

Request ........................................................................................................................................ 9 Response ................................................................................................................................... 10

Sample Requests / Responses 14

GetInsightsMetrics by Customer and Contract ............................................................... 14 GetInsightsMetrics by Customer ........................................................................................ 16 GetInsightsMetrics by Customer and PLC ......................................................................... 19

Formatting Standards 21

Error Messages 22

HTTP Status codes & errors .................................................................................................. 22 400 Bad Request errors ......................................................................................................... 23

GetInsightsMetrics Service Reference Manual Contents • iii

Tables Table 1: Detailed JSON Request Structure ............................................................................................ 10 Table 2: Detailed JSON Response Structure ......................................................................................... 13 Table 3: HTTP Status Codes & Errors ...................................................................................................... 22 Table 4: 400 Bad Request Errors ............................................................................................................. 23

Figures Figure 1: Product Pool example .................................................................................................................. 7 Figure 2: Prorated Metrics example .......................................................................................................... 7

Autodesk Partner WebServices GetInsightsMetrics Service Reference Manual • 4

Introduction

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 JSON data-interchange format.

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 developers and 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.

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.


Service Overview

Service Purpose Autodesk reseller partners will benefit from having better visibility of end customer's usage so they can support the end customer effectively through product adoption, training and ongoing use of the Autodesk products they are subscribed to. They will also be able to leverage usage data to identify the most logical areas where an end customer may need more seats, additional or different products and will understand better about the likelihood of continued use of the products, provide sales help or support as required and ultimately ensure renewal.

The current workflow for partners to attain usage information is that the customer primary admin allows the partner to be secondary admin and go into account and pull an export of the usage information. However, this isn't ideal in case the customer does not want to give access to the partner or if the partner has a lot of customers and has to log into each account to view usage. Our API will be automating this process and they will be getting the usage information directly through a call to the API Service.

Insights is a set of metrics that describe the seat usage of end customer's products and the likelihood that an agreement will renew.

EWS Insights Metrics • Seats Assigned: Number of users assigned to assets purchased by the customer

• Seats in Use: Number of seats used in the last 30 days

Goals • Allow better visibility into End Customer’s seat usage to better support customer effectively

through product adoption, training and ongoing use of the Autodesk products they are subscribed to.

• Current workflow to get access to customer’s usage data is a manual process and we want to provide an automated solution

• EWS Insights is a set of metrics that describe the seat usage of end customer's products

• Insights specific attributes: Seats Purchased, Seats Assigned, Seats in Use

Coverage • EWS Insights Metrics will cover Single User Subscriptions


o 95%+ SUS covered

§ 99.7% of scored SUS have only one reseller per agreement

• In that case, direct metrics can be shown to the partner owning this agreement.

§ 0.3% of scored SUS have more than one reseller

• In that case shared Metrics will be prorated

• EWS Insights Metrics will not show any metrics for Network/Multi seat subscriptions

• EWS insights Metrics will only show data for commercial subscriptions

• All the metrics will be updated daily

Limitations • If there is a 1:1 association between product pool and agreement, then you will get direct seat

metrics

o If there is more than one agreement per product pool, then you will get prorated metrics

• If there is a 1:1association between product pool and reseller, then you will get direct seat metrics

o If there is more than one reseller per agreement, then you will get prorated metrics


Product Pool A product pool groups seats into pool regardless of what contract or subscription they are from:

Figure 1: Product Pool example

Solution for Limitation When pro-rated metrics are displayed instead of direct metrics, Partners will see Seat Assignment and Seat Usage as a percentage of the total Product Pool. Prorated seat assignment and usage will always equal the pool assignment and usage.

Figure 2: Prorated Metrics example

End Customer

123

Subscription 1 of ACAD – 5

seats

Subscription 3 of ACAD – 10

seats

Subscription 2 of Revit – 12

seats

ACAD pool-15 seats

Revit pool-12 seats


Service Endpoints

Staging https://enterprise-api-stg.autodesk.com/v1/insightsMetrics

Production https://enterprise-api.autodesk.com/v1/insightsMetrics


Service Request & Response

Request The following tables explain the schema for the Request of the GetInsightsMetrics service.

Please note that:

• Bold denote objects and arrays

• Cardinality: (M) Mandatory, (O) Optional

Field Card. Description Format Example Style Authorization M Access token received from the initial

OAuth token generation call (*) String Bearer

xx1ntfi1lJO7DoWJx7Xtp76Zjqp8

HEADER

timestamp M epoch time 10 Digits accurate to the second when the signature is generated (*)

Long Integer 1589796198 HEADER

signature M Unsalted SHA-512 hash of the concatenation of the callback URL, access token and timestamp (*)

String Bhc0JISIITPkoYHlpsLyWAeg6SPKBKt3cNy93Hruupo=

HEADER

CSN M CSN of the Partner invoking the API String (10) 5000000000 HEADER

customerCSN O End Customer CSN number 5100458348 PARAM


contractNumber O Contract Number number 110001723548 PARAM

plc O Product Line Code string ACD PARAM

Table 1: Detailed JSON Request Structure

* Please refer to https://partner.developer-stg.autodesk.com/contents/files/user-guides/en/pws-api-authentication-guide.pdf for API Authentication details.

Response The following information represents the response schema for the GetInsightsMetrics service.

Please note that:

• Bold denote objects and arrays

• Cardinality: (M) Mandatory, (O) Optional

Field Card. Description Format Example Visibility [{ 1..N Object

customerCSN Account CSN number 5100458348 Sold-to or RoR

contractNumber Contract Number or Subscription number number 110001723548 Sold-to or RoR


ownerType Type of owner (If it is marked as an individual it will be marked as contact else account)

string ACCOUNT Sold-to or RoR

productLineCode Product line code string ACD Sold-to or RoR

seatsPurchased Latest count of Seats purchased for each product offering under a contract

number 60 Sold-to or RoR

usersAssigned Latest count of User assigned to the offering product lines under a contract.

This column is has numbers when there is a 1:1 relationship between Pool (tenant/Product) and agreement.

In case of a 1:many relationship, the value is set to null.


seatsInUse Latest Count of assigned users who have used (authorized) at least once within the 30 days observation period



This column is has numbers when there is a 1:1 relationship between Pool (tenant/Product) and agreement.

In case of a 1:many relationship, or if the agreement is out of scope, the value is set to null.

usersAssignedProRated In case several agreements are associated to a pool, a pro ration factor will be applied to the pool assignment to only allocate a portion of the assignment relative to the seat purchased under each agreements.

The factor is equal to (seat purchased of a specific agreement) / (Sum of seats purchased for all agreements)

This column is has numbers when there is a 1:many relationship between Pool (tenant/Product) and agreement.

In case of a 1:1 relationship, or if the agreement is out of scope, the value is set to null.

number null Sold-to or RoR

premiumFlag Flag equal to 1 if premium has been purchased for this tenant / pool.

0 if not

Boolean False Sold-to or RoR


tenantId Team id for single user subscription number 8686008 Sold-to or RoR

resellerCSN CSN of Reseller listed at the agreement / product level

In case several resellers exist at the agreement product level, this field will be null


resellerName Name of Reseller listed at the agreement / product level

In case several resellers exist at the agreement product level, this field will be null

string Partner ABC Sold-to or RoR

}]

Table 2: Detailed JSON Response Structure


Sample Requests / Responses The following information are sample requests and responses to be used as reference.

GetInsightsMetrics by Customer and Contract Service Request

/v1/insightsMetrics?customerCSN=5116603100&contractNumber=110002156707

Method : GET

Headers :

Authorization : Bearer {token}

content-Type : Content-Type

signature : signature

timestamp : template

partnerCSN: 5070146073

Service Response {

"status": "ok",

"transactionId": "63e1d3bf-283e-40f4-93d0-0816ccfda2b1",

"message": [

{

"customerCSN": 5100123134,

"contractNumber": 110001359168,

"ownerType": "ACCOUNT",

"productLineCode": "ACDLT",

"seatsPurchased": 12,


"usersAssigned": 12.0,

"seatsInUse": 6.0,

"usersAssignedProRated": null,

"seatsInUseProRated": null,

"premiumFlag": false,

"tenantId": 9214716,

"resellerCSN": 5070155615,

"resellerName": "Reseller ABC"

}, {




"productLineCode": "PDCOLL",


"usersAssigned": 3.0,

"seatsInUse": 3.0,




"tenantId": 9214716,


"resellerName": " Reseller ABC "

}

]

}


GetInsightsMetrics by Customer Service Request

/v1/insightsMetrics?customerCSN=5116603100

Method : GET

Headers :






Service Response {

"status": "ok",


"message": [

{



"ownerType": "CONTACT",

"productLineCode": "AECCOL",


"usersAssigned": null,

"seatsInUse": null,





"tenantId": null,


"resellerName": "Reseller LTD"

}, {




"productLineCode": "ADSTPR",



"seatsInUse": null,




"tenantId": null,



}, {








"seatsInUse": null,




"tenantId": null,



}, {







"seatsInUse": null,




"tenantId": null,



}

]

}


GetInsightsMetrics by Customer and PLC Service Request

/v1/insightsMetrics?customerCSN=5146989386&plc=AECCOL

Method : GET

Headers :






Service Response {

"status": "ok",


"message": [{







"seatsInUse": null,





"tenantId": null,


"resellerName": "Reseller Tech"

}

]

}


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


Error Messages

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 3: HTTP Status Codes & Errors


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 45004 No Insights Metrics data found No data found matching the query

parameters

45011 No Partner-Association Match found for this request.

Table 4: 400 Bad Request Errors

PWS GetInsightMetrics Service Reference Manual v1.0

Documents

Transcript of PWS GetInsightMetrics Service Reference Manual v1.0