File Upload API Reference

Owned by Jarin Thundathil
Last updated: Dec 03, 2024
6 min read

This guide covers usage of the GraphQL API to create and modify assets in your asset library. Scope uses the Apollo file upload protocol to upload assets using multi-part GQL requests.

 

There are two file upload operations:

  • createAsset - for uploading a new asset to your library

  • updateAsset - for modifying existing assets in your library

Both require that you configure a multi-part GraphQL request using an HTTP or GQL Client. The examples in this guide use Postman to configure upload parameters.

 

We’ll cover three use cases:

  1. Uploading a file as the author

  2. Uploading a file on behalf of a user

  3. Creating a folder

 

Prerequisites

High Level Flow Diagram

This is the high-level flow diagram for the operation of uploading files to the WorkLink asset libraries.

Note that the diagram above assumes that you are obtaining the token from an IDP system for an SSO user. Other options for authentication include:

  1. The token being used is an API token provided by WorkLink in which case steps 1 and 2 are skipped and the token is provided to the PLM directly. See here for more details.

  2. The token is being provided by WorkLink for a non-SSO user. In this case steps 1 and 2 would go to WorkLink for authentication rather than an IDP.

Uploading a file as the author

To recreate an Apollo file upload request in Postman, you can follow these steps to mimic how Apollo uploads files via a GraphQL multipart request.

 

Note: The request template provided here generalizes to all three use cases with slight modifications.

 

What you need

  1. A valid user token

  2. An HTTP client - The steps shown below describe using Postman.

 

Procedure

  1. Open Postman and create a new collection

  2. Click on the collection, go to the variables tab, and add the following variables and set their values

    1. company_permalink

    2. username

    3. password
      The values should be your username and password, and the company permalink can be found on your company profile page on the CMS.

  3. Make sure to save the collection after you are done creating those variables.

  4. Within new collection create a new request and set it to an HTTP POST request type.

    Click the ‘+' icon in the top right to create a new request, and choose the 'POST’ option from the dropdown menu on the left. You can enter the GQL endpoint in the URL field.

  5. Enter the GQL endpoint URL: https://cms.scopear.com/api/v3/graphql/?permalink={{company_permalink}} in the URL field.

  6. Go to the Body tab:

    • Select the form-data option.

Note: You'll need to add multiple key-value pairs here, similar to how a GraphQL multipart request is structured.

Example of the ‘Body’ tab and relevant keys to enter. The content of those keys is given in steps four, five, and six.

  1. Add the operations field:

    • In the key field, enter operations.

    • Set the type to Text.

    • In the value field, you need to input a JSON object describing the GraphQL mutation and variables.

    • Example of JSON Object to specify variables:

      "variables": { "input": { "file": null } }

    • Example of completed JSON Object with query and variables:

      { "query": "mutation createAsset($input: CreateAssetMutationInput!){ createAsset(input: $input) { asset { id databaseId name type createdBy { databaseId name } owner { ...on User { id databaseId name } ...on Organization { id databaseId name } } originalFile { fileUrl } }, errors { fullMessage, message, path, type } } }", "variables": { "input": { "file": null } } }

    • Note: By default, the "createdById" argument will be set to the current user's ID. The "name" arg will be set to the file name. Folder will be set to null, meaning the asset will be added to the root of the Personal Library.

  2. Add the map field:

    • In the key field, enter map.

    • Set the type to Text.

    • The value should be a JSON object that maps the file to the variable in the operations object. Example:

      { "0": ["variables.input.file"] }

This indicates that the first file (index 0) will be assigned to the file variable in the mutation.

  1. Add the file itself:

    • In the next key field, enter 0 (this corresponds to the key specified in the map field).

    • Set the type to File.

    • Upload the file you want to send.

  2. Set the request headers:

    • Postman automatically detects this is a multipart request. However, you should ensure that the header for Content-Type is set to multipart/form-data.

    • Add the Authorization header with your access token. Example:
      Authorization: Token token=eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7InVzZXJfaWQiOjY1NzA3LCJkZXZpY2VfaWQiOjIwMzM3LCJjb21wYW55X2RhdGFiYXNlX2lkIjoxLCJjb21wYW55X2dxbF9pZCI6IndlaUllck1tTGh1T1RSOTFXVDRhMmFIazRpaUpXT1I5MUpsVWM4Tl9IRE9wSE41Ym1HWk5na2lrbHg5dXdFamwiLCJjb21wYW55X3Blcm1hbGluayI6InNjb3BlIn0sImV4cCI6MTcyODc2MDM3NywianRpIjoiMGRhMDgwMTcyMWZiNjI4MzA5ODVhNDZkY2FkNWM2Y2RlNmRhMzRhNTFiNmI4NTg1OTdiZWY2MjliNjBjOTNmNyIsImlhdCI6MTcyNjE2ODM3N30.TePbk7-MkEtIBk1npnV7DEPmtQ9HHvnwm5pSPhTK8Wk

    • If this doesn’t work, you can try using a bearer token instead:

      • Click on the Headers tab.

      • Add a field under Key titled Authorization.

      • In the Value field, enter your bearer token: Bearer <yourtokenstring>

  1. Send the request:

    • Now, you can send the request, and it will mimic an Apollo GraphQL file upload.

 

Sample Response:

Uploading a file on behalf of an author

An asset can be uploaded on behalf of an author to either their personal asset library, or to the company assets library, while assigning ownership to the specified author. This can be accomplished using the credentials of an admin user.

Note: The procedure is identical to uploading a new asset with the exception of the variables entered in step 4, and the token entered in step 7. See Uploading a file as the author to read the steps in detail.

 

What you need

  1. User credentials for a user with admin access

 

Sample Variables

  1. name: Defaults to the file name

  2. createdById: Refers to the library the asset will belong to. If passing the author ID, the asset will be part of their Personal Assets list. If passing the Organization ID, the asset will end up listing under 'Company Assets'.

  3. file: populated by multi-part Apollo Upload.

  4. folderId: optional - In case you need to upload the asset directly into a folder. The folder asset needs to belong to the same ownerId.

Creating a folder

Folders are unique types of assets that don’t require a file to be uploaded. You can simply specify a name and, optionally, a parent folder if you want to create a folder tree.

 

Note: Once again the procedure is nearly identical to uploading a new asset with the exception of the variables entered in step 4. See Uploading a file as the author to read the steps in detail.

 

What you need

  1. A valid admin or user token

  2. Optional: A parent folder ID

 

Hint: How to Browse the Current List of Folders in Your Asset Library

If you need to find the name and gql-id of a parent folder in your asset library to upload your new folder to, you can use a GraphQL query like this one:

 

If you’d prefer to list the current company’s folders, you can use a GraphQL query like this:

 

Note: In both cases, you can browse assets in general rather than folders by removing the “types” filter from your query.

 

Sample Variables

  1. type: Mandatory when creating folders.

  2. folderId: Optional. When left null, the new folder is in the root directory.

  3. ownerId: Optional. This is the root library the folder will belong to, which is the author ID by default. By passing the author ID, the folder will be part of their Personal Assets list and by passing the Organization ID, the folder will end up listing under ‘Company Assets’. Nested folders need to belong to the same ownerId as the parent.