SharpCloud Developer Documentation

 

Overview

SharpCloud can be customized to fit your requirements. 

Most customization can be achieved without any developer skills.

Where developer skills are needed, this section is designed to help you along that journey. 

 

Developer efforts can be split into two categories: 

1. UI Behaviour – Developing and customizing plugins (Front-end) 

2. Data Integration – Using REST API’s to get data in to the platform (Back-end)

 

-----------------------------------------------------------------------------------

UI Behaviour – Plugins (Front-end) 

We implement visual extensions to SharpCloud stories using Plugins. 

 

Plugins are custom bits of code that run from an iFrame hosted in the View or Item Panel. They are built using HTML/CSS/JavaScript and interact with SharpCloud via the Client SDK.

Examples:

• a new visualization
• custom reports
• data entry forms
• a user initiated behaviour (like sending messaging or initiating an external workflow.)

 

SharpCloud already includes many free plugins, via the plugin store.

• You can view the plugins by
  • adding a Widget View to a story
  • adding a Plugin Panel to an item. 
• The plugins include source code
  • You can use the source code to see how behaviours are achieved.
  • You can also use it as a starting point for your own.
  • We provide templates to get you started quickly. 

 

Development Prerequisite

1. Access to “Storage Manager” which allows you to upload your code to SharpCloud.
   1. Storage Manager is free but not available if you’re using one of our multi-tenant environments:
      • https://app.sharpcloud.com
      • https://my.sharpcloud.com
      • https://uk.sharpcloud.com
      • https://eu.sharpcloud.com
   2. It also needs to be enabled by your System Administrator. You can think of Storage Manager like SharpCloud’s version of JSFiddle. 

Plugins generally do not require any authentication as they will run in-line in the browser and behave as the user using them. 

Check out the videos at the end of this article that will walk you through the journey of building Plugins.

 

--------------------------------------------------------------------------

 

Data Integration – REST API’s (Back-end) 

 

Data flow can be automated to SharpCloud using our public REST API’s. 

Documentation and Authentication

API Documentation

Comprehensive API documentation is available through the Swagger interface, which provides:

• • A complete list of available API endpoints

  • Details on supported request and response data types

  • Interactive examples and code snippets for testing API calls

The Swagger interface can be accessed from the Profile menu after signing in to the application.

Authentication

The API supports the same authentication and permission model as the application.

• • When signed in to SharpCloud, the Swagger interface can execute requests using the currently authenticated user account.

  • For external applications or remote API calls, generate a Personal Access Token (PAT) from the Profile menu.

  • Include the PAT as a Bearer Token in the Authorization header of API requests.

 

The Swagger interface also supports Bearer Token authentication, allowing requests to be tested directly and providing examples of the exact request format used by the API.

 

Access Permissions

The API enforces the same access controls and business rules as the standard web application. Actions performed through the API are limited by the permissions assigned to the authenticated user.

• Read Access: Stories can only be viewed if the user has Read-Only access or higher.

• Create, Update, and Delete Access: Stories can only be created, modified, or deleted if the user has Collaborate/Create permissions for those stories.

If a user does not have the required permissions in the application, the same restrictions will apply when accessing the data through the API.

Licensing and API Access

Any user with an active SharpCloud subscription can access data through the public APIs. By default, write operations are subject to a rate limit of 60 requests per hour.

If your integration requires a higher volume of write operations, this limit can be reviewed and adjusted on a case-by-case basis. Contact SharpCloud Support for assistance.

Available APIs

SharpCloud provides two public APIs, both of which operate against a specific story and therefore require a Story ID as part of the request. Current API functionality does not support calculations, as these are performed client-side within the application.

The available APIs are:

1. Batch API

2. OData API

Batch API

The Batch API is the recommended option for importing and exporting large volumes of data. It exchanges information in JSON format using normalized, user-friendly field names rather than internal system identifiers.

For example:

{
  "Category": "Project",
  "ExternalID": "A100",
  "Name": "My Project",
  "Cost": "300",
  "Risk": "Medium"
}

This format makes integrations easier to develop and maintain. The Batch API currently supports bulk operations for:

• Items

• Relationships

• Panels

• Resources

ExternalID Requirements

All items managed through the Batch API must include an ExternalID, which serves as the unique reference between SharpCloud and the source system.

Key considerations:

• Maximum length: 200 characters

• Unique within a category (not across the entire story)

• Used to identify records for create, update, and delete operations

• Cannot be modified through the Batch API

For example, both of the following are valid:

• Project → ExternalID = 001

• Risk → ExternalID = 001

because they belong to different categories.

When processing data:

• If no matching Category + ExternalID combination exists, a new item is created

• If a match exists, the item is updated

• Deletes can be performed explicitly or through batch synchronization options

Limitations

The Batch API is designed for data synchronization and cannot modify story structure. Operations such as creating categories, attributes, or tags require the OData API.

Data Connectors and Extracts

Many import and export scenarios can be handled without custom development by using SharpCloud Data Connectors and Data Extracts.

These tools provide ETL (Extract, Transform, Load) capabilities and include advanced SQL support for:

• Data transformations

• Grouping and aggregation

• Arithmetic calculations

• Joining data from multiple sources

Data Connectors and Extracts use the public Batch API behind the scenes to read and write data to SharpCloud.\

Note: SharpCloud provides tools for importing and extracting data but does not provide tooling to push data directly to external systems. Such integrations typically require custom development.

OData API

The OData API provides advanced access to SharpCloud data and story configuration using the industry-standard OData protocol.

Documentation is available by selecting Public API V1 (ODATA) from the Swagger interface.

Unlike the Batch API, OData references objects using internal identifiers (GUIDs), making it more powerful but also more complex to use.

When to Use OData

OData is recommended when you need to:

1. Modify story structure programmatically (categories, attributes, tags, etc.)

2. Delete items that do not have an ExternalID

3. Rename an item's ExternalID

4. Perform advanced filtering and queries

Example query scenarios include:

• Items whose name contains specific text

• Items where a numeric attribute exceeds a threshold

• Complex multi-condition searches across related entities

For most data import and export scenarios, the Batch API remains the simpler and more scalable solution. OData should be used when structural changes or advanced querying capabilities are required.

If you require assistance selecting the appropriate API or designing an integration, contact SharpCloud Support for guidance.

 ---------------------------------------------------------------

Plugin Walkthrough Videos