Follow

Assemble Event API

The Assemble Events API gives you access to the auditing activity logs produced by and through our web app and lets you retrieve them for use in your own app.  The API is RESTful and is focused on providing visibility into the activity logs generated by Assemble.  Assemble stores event activity for a minimum of 30 days, to provide the ability for you to retrieve the data when you need it without having to be constantly polling for fear of losing data.

The Assemble Events API has no default client application.  You will need to create an application to authenticate, request, store, and filter the event records.  Assemble Systems has sample code you can use to begin to develop your application, or to serve as a guideline on the functional aspects of communicating with the API.  It is available upon request.  Below we will cover those functions necessary for retrieving data via the Assemble Events API.

Setup

In order to access the Assemble API for your site, you will need to contact Customer Support and have API access enabled for your site.  You will need to provide a Client ID for your application and the email for a user that is authorized to access the API. Upon request, Customer Support will provide you with a Client Secret to go with your Client ID and enable API access for the requested user to allow your application to authenticate and gain access to the API.

Glossary

stream_position: Position in the stream of events.  Parameter passed to indicate the approximate starting point of of your requested block of events

event_id: Unique identifier given to each event.  Used for detecting duplicates.

Limit: Number of events to return in response to a request.  Max 2000.

access_token: Token passed with each request to verify access.  Has a shorter expiration and must be refreshed periodically.

auth_code: Token returned to you once you have successfully logged in

client_id: The equivalent of a API user ID.  Cannot be used to log into Assemble

client_secret: The equivalent of an API password.

redirect_url: address you specify where we return the auth_code

refresh_token: Token passed to request a new access token. Token can only be used once and has a longer expiration. A new refresh token is returned with every refresh request. 

Date Format

All time stamps (both those sent in requests and those returned in responses) should be formatted as shown in our examples. We support RFC 3339 timestamps. The required format to pass in a date is by converting the time to UTC such as this: 2013-04-17T09:12:36-00:00.  All event time stamps are recorded and reported in UTC.

Authentication

The Assemble API uses OAuth 2 for authentication.  An authorization header containing a valid access token must be included with every API request.  Authentication is a five step process that works like this:

    • Authorization Request - Your application will send an initial request for an authorization code (auth_code) with the Client ID.
    • Login - You will be prompted for an email & password via a web page
    • Authorization Response - We return a response with the authorization code to the redirect url (redirect_uri) you specify
    • Access Token Request - You send a request for an access token (access_token) with the authorization code (auth_code), Client ID, & Client Secret
    • Token Response - We return an access_token 

You will then need to pass the access_token on all subsequent requests to the api, refreshing as needed (see below).

 Authorization Request

The following are the query string parameter values that need to be supplied to submit an Authorization request.

Parameter

Data type

Required

Description

response_type

string

Yes

Must be “code”

redirect_uri

uri

Yes

A URI where the response will be sent.

client_id

string

Yes

Your Client ID

state

string

No

Optional.  Returned in the auth response. Used to track current state/returning session.

Begin by sending a request to the Assemble Hub.  Please note: we only support SSL for API access.  The basic form of the request is as follows:

https: //assemblehub.tryassemble.com/Hrd?client_id=<YourClientID>&redirect_uri=<YourRedirect_URI>t&response_type=code&state=init

The redirect URI needs to be properly formatted so that the API can return it to you as part of the redirect response.  The redirect takes place after you login, and contains your auth_code.  The redirect URI can be used to redirect to an internal application or webpage.

Login

The authorization request will redirect you to the Assemble Login page.  From there you must enter the email address and password for the user authorized to have Assemble Events API Access.  The Assemble login page is a straightforward HTML form.  If your Assemble organization is configured to use third party authentication you will be directed to authenticate with it.

Authorization Response

Assemble’s response to a successful login will be in the format of a URI redirect with your authorization code provided in the code parameter of the query string.  You will need to retrieve the auth_code for use in obtaining an access_token.

Example response headers:

Key

Value

X-AspNetMvc-Version

4.0

X-UA-Compatible

IE=edge,chrome=1,requiresActiveX=true

Content-Length

184

Cache-Control

private

Content-Type

text/html; charset=utf=8

Date

Fri, 09 May 2014 05:16:10 GMT

Location

URN:test?code=<auth_code>&state=init

Set-Cookie

HubBearer=<>; expires Sat, 09 May 2015 05:16:10 GMT; path=/

Server

Microsoft-IIS/7.5

X-AspNet-Version

4.0.30319

Access Token Request

The access token request will take an authorization code and application client id and client secret and return a valid access token to be used with each API request.

Body of the POST must be a JSON object with these parameters: code, client_id, client_secret,  and scope. The parameters and values are case insensitive.

Parameter Type Required Description
code string yes Authorization code you received from step 1
client_id string yes Your Assemble client ID you received from Assemble support
client_secret string yes Your Assemble client secret you received from Assemble support
scope string yes Currently, we only support "eventsapi"
https://assemblehub.tryassemble.com/api/OAuth

 

Token Response

In response to the token request, Assemble will provide a token response  that is a JSON object  with the following values. The token response consists of the following values. The expiration of the access_token can be used to determine ahead of time when an access_token will need to be refreshed. The refresh_token is used in the Token Refresh process to obtain a new access_token.

Parameter Type Description
access_token string This is the token that grants you access to the api and is the value that must be supplied in the authorization header with every api request.
token_type string This will currently always be "HubBearer".
expires_in string This is the number of seconds after the access token is created for which it is valid.
refresh_token string This is the value that must be supplied in a token refresh request to get a new access token if the current one has expired.

 Example token response: 

{

"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJpc3MiOiJodHRwOi8vYXNzZW1ibGUuaHViLmludGVybmFsYXNzZW1ibGUuY29tIiwiYXVkIjoiaHR0cDovL2Fzc2VtYmxlLmh1Yi5pbnRlcm5hbGFzc2VtYmxlLmNvbS9wdWJsaWNhcGkiLCJuYmYiOjEzOTg3OTAwN zIsImV4cCI6MTM5ODc5MzY3MiwiaHR0cDovL2Fzc2VtYmxlc3lzdGVtcy5jb20vQXNzZW1ibGVDbGFpbVR5cGVzL05vbkFzc2VtYmxlL0V4dGVybmFsU2Vzc2lvbklkIjoiOGVmMDQ5OTAtOGRmMC00ZWYxLWIyY2UtZjFiNDhkMmEyMWQ3IiwiaHR0cDovL2Fzc2VtYmxlc3lzdGVtcy5jb20 vQXNzZW1ibGVDbGFpbVR5cGVzL05vbkFzc2VtYmxlL0ludGVybmFsQmVhcmVyVG9rZW4iOiIyZDViMmEwYi00MDA5LTRmOWItYTYxNS00NzJmZTRlZDVjN2UifQ.",

"token_type":"HubBearer", 

"expires_in":3599, 

"refresh_token":"7c1a41fc-0b17-4acf-98d9-01af6980 e8b1"

}

Token Refresh

Your application will need to monitor the expiration of your access_token and refresh it before it expires.  The access_token expires approximately every 4 hours.  We recommend you refresh at least 5 minutes before the token expiration. If your access token is expired, you will receive a 401 (Unauthorized) Http status code. If you have a valid unexpired refresh token, then you can use that to get a new access token as shown here. Refresh_tokens are single use tokens that are used to acquire a new access_token and are good for approximately 7 days. When a new access_token is received, a new refresh_token is received as well with a new 7 day expiration. 

You refresh the token by POSTing a request to the URL below.  In the body of the html document you will need to include a JSON object containing the required parameters below.  The parameters and their values are case insensitive  The response will return a JSON object with new tokens and new expiration information. 

Parameter

Data type

Required

Description

Default

client_id

String

Yes

Your Assemble client ID you received from Assemble support

 

client_secret

String

Yes

Your Assemble client secret you received from Assemble support

 

scope

String

Yes

Requires default value

eventsapi

grant_type

String

Yes

Requires default value

refresh token

refresh_token

String

Yes

Current refresh token

 

https://assemblehub.tryassemble.com/api/OAuthToken

Logout

In order to completely revoke access of the current credentials, your application should perform a log out. This will immediately invalidate the existing access_token and refresh_token.  Your application should do this by simply calling:

https://assemblehub.tryassemble.com/api/OAuth/Logout

Understanding the Event Stream

The events in the Event Stream are a combination of events recorded by your web site and our authentication service.  Events are registered against a time-sequenced list called the stream. The stream is a collection of events from all assemble services. Because these events come from different areas of the infrastructure it is possible that the events may appear to be out of order or end up with “duplicate events”.

Each event has a unique event_id associated with it. These event_ids are not always sequential, and are merely reference pointers to our internal systems.  The event_id can be used to filter out duplicate events. It is possible to have gaps in event_ids.  These gaps are not meaningful and do not indicate missing or additional relevant events.

When you request a block of events based on the stream_position, we look back slightly in the stream to make sure no events were posted before that event_id that you may not have gotten in your last request.  If we think there might be, we will include those events in our response to your request.  This means sometimes you will get duplicate events, but we would rather err on the side of giving you duplicates than possibly missing a relevant event in the set we send to you.  We will return the stream of events to the end of the stream or the Limit, whichever comes first.  The Limit parameter defaults to 100 if not specified in the request.  The upper bounds for Limit is 2000.

Event Requests

Each request must contain the access_token provided in the previous step.  This should be passed in the request header in the format "Authorization" = "Bearer " + access_token. The request should be in this format: “https://<yoursitename>.tryassemble.com/api/v1/Events?StreamType=admin_logs&Limit=100”

To initialize your client to use the Events API endpoint, you should call Events API  with either stream_position=0 or no stream_position parameter set. If you do not send in a stream_position, we default to the first event we have in your stream.  Your application is then expected to call the Events API endpoint with new stream_position values, as returned to you with each response, until you get no events and have an event count of 0. For example, to return data starting at the next stream position (event O15-131):  

“https://<yoursitename>.tryassemble.com/api/v1/events?StreamType=admin_logs&StreamPosition=131”

It is possible that when you make a request you would get a NextStreamPosition that does not exist in the event stream. This is because NextStreamPosition is a best guess as to what the next position is and not necessarily a pointer to the next event.  Below is a list of other parameters that can be passed to the EventsAPI. Each additional added parameter is inclusive to the others. For example, to return up to 2000 events that were created after 5/4/2014 that have a type of 310:

https://<yoursitename>.tryassemble.com/api/v1/Events?StreamType=admin_logs&Limit=2000&CreatedAfter=2014-05-04T00:00:00&Types=310

It is possible to have 0 events returned either because of the filters you used or you are at the end of the stream. In your response you will have an event count of 0. It is up to you to determine which of these conditions you have encountered.

The query parameters and values are case insensitive: 

Parameter

Data type

Required

Description

Default value

StreamType

String

Yes

Must be admin_logs

 

StreamPosition

String

No

Position in the event stream from which to begin returning events. Value should be obtained from the next stream position in the previous response.

0

CreatedBefore

timestamp

No

Return events created no later than the specified date and time.  Specify in UTC

(Example: 2014-04-25T14:34:27)

See note on Date Formats, below

none

(All events)

CreatedAfter

timestamp

No

Return events created no earlier than the specified date and time.   Specify in UTC

(Example: 2014-04-25T14:34:27)

See note on Date Formats, below

none

(All events)

Limit

Integer

No

Return up to this number of events.

Must be between 1 and 2000.

100

Types

String

No

Return only events that match the specified types. Value must be a comma separated set of values indicating the event types to be returned. Types can be specified by either the name or the numeric value. See the list of Event Types for possible values.

none

(All events)

Returned Event Types

Below is a list of the event types that can be received in the event log.

Estimate actions

    • CreateEstimate = 101

User actions

    • CreateUser = 201
    • UpdateUser = 202
    • OpenUser = 203
    • DeactivateUser = 204
    • ActivateUser = 205
    • AcceptInvitation = 210
    • InviteUser = 211
    • ChangePassword = 212
    • ResetPasswordRequest = 213
    • ResetPassword = 214
    • FailedLogin = 215
    • Login = 216
    • RefreshToken = 217
    • SiteAccessDenied = 218
    • GrantUserApiAccess = 219
    • RevokeUserApiAccess = 220
    • SiteAccessGranted = 221
    • Logout = 222
    • GrantThirdPartyApiAccess = 241
    • RevokeThirdPartyApiAccess = 242

Project actions 

    • CreateProject = 301
    • UpdateProject = 302
    • OpenProject = 303
    • ArchiveProject = 304
    • UnarchiveProject = 305
    • DeleteProject = 306
    • AddProjectUser = 310
    • RemoveProjectUser = 311
    • UpdateProjectUser = 312 

Model actions 

    • CreateModel = 401
    • UpdateModel = 402
    • OpenModel = 403
    • DeleteModel = 406 

Model View actions 

    • CreateModelView = 501
    • UpdateModelView = 502
    • OpenModelView = 503
    • DeleteModelView = 506
    • ImportModelView = 507 

Model Version actions 

    • CreateModelVersion = 601
    • UpdateModelVersion = 602
    • OpenModelVersion = 603
    • DeleteModelVersion = 606
    • CompareModelVersions = 611
    • UpdateModelVersionProperties = 622
    • SynchronizeAll = 630
    • SynchronizeView = 631
    • SynchronizeProperties = 632 

Model Version Export actions

    • ExportExcel = 701
    • ExportNavisworks = 702 

Assembly Code actions

    • ImportAssemblyCodes = 801
    • ExportAssemblyCodes = 802 

API actions

    • ApiGetEvents = 901

Return Codes

The Assemble API returns standard HTTP return codes for each request. 

    • 200: Request successful.  We will return this for valid requests that return no data.
    • 400: Bad Request.  Usually a parameter value that is invalid or out of scope
    • 401: User not authorized. Usually expired tokens
    • 403: User not allowed.  API access not enabled
    • 404: Request not found.  Bad URL formatting.
    • 500: Unavailable: System issue at Assemble
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk