Documentation

📓 Glossary

Suggest Edits

App project

What's an App Project on Edusign?

An App Project (or an app) is the plugin itself which contains everything regarding one specific app, it contains the following :

App informations

What are the basic informations of my app?

The "Informations" tab regroups the basic informations of your app, such as its name or its purpose :

📖

Create relevant apps

Be as specific as possible : what will your app do? Why should someone use it or install it?
Even if you are planning to keep it as a private app, it's important to add as much information as possible.

  • App name : The name displayed for your app
  • Description : The description displayed in the details of your app on the app marketplace
  • Short description : The short description displayed on the homepage of the App Marketplace (if the app is public)
  • Technical contact email : The email must be valid for publishing the app
  • A logo for your app
  • Redirection URL(s)

API keys and permissions

What can I access on Edusign through my app?

The "API keys" tab regroups everything linked to your API keys as well as your app permissions :

API keys

You can retrieve here :

  • Your Client ID : The App ID, used for the SSO IDP system
  • Your Client Secret : Used for the SSO IDP and also to verify the webhooks HMAC integrity
  • Your API Key : Required for accessing the Edusign REST API

🔍

SSO, Webhooks and API :

Permissions

You can define here the level of permission your app should have for each feature :

There are three levels of permissions :

  • No access : Your app don't have access to the ressource
  • Can read : Your app will have a read-only access to the ressource
  • Can read, create and update : Your app will be able to read, create and update the ressource

📖

Permissions used wisely

Make sure that the permissions you are requesting are relevant to the scope of your application.
You can retrieve our publishing guidelines here.

Webhooks

How can I trigger webhooks for my app?

The "Event subscription" tab lists the webhooks which can be created for your app :

A POST request will be send to the Webhook URL every time that particular action will be performed.

As for now, one Webhook URL can be provided for each trigger.

🔍

Webhook triggers

You can retrieve our list of available triggers here.

App actions

How to display an element of my app on a specific page?

Actions

The "Actions" tab allows you to define on which page(s) your app (for instance a block) is going to be displayed :

An app action is structured as followed :

  • A platform : On which platform are we displaying the URL?
  • Teacher platform : The platform used by teachers for assiduity
    • A view : On which page are we displaying the URL?
  • Student platform : The platform used by students for assiduity
    • A view : On which page are we displaying the URL?
  • URL : The action to execute, in this case an URL call to get blocks.

🔍

Block builder

You can retrieve our block builder library here.

Placeholders

App actions are displayed in a drawer on the right side of associated page on the platform, the drawer can be opened when clicked on this button :

The button to open the applications drawer.

The button to open the applications drawer.

And the drawer itself looks like this, with the different apps stacking one after each other :

The drawer itself, an example here with two different apps.

The drawer itself, an example here with two different apps.

🦉
Open Recipe

App parameters

How to let the user set values on my app?

The app parameters are environment variables dedicated to the app, they are linked to the App Project (the app project has a JSON with the app parameters names), the app parameters contains all the values that the user can configure in the app page.

Creating a new app parameter

Creating a new app parameter.

Retrieve App Parameters with Installation URL

When an installation URL is configured for your application, with each new installation of the application, a call is made to your installation URL.

You will then receive the following information in the request body:

{
  schoolId: "<SCHOOL_ID>",
  client_id: "<APP_ID>",
  client_secret: "<CLIENT_SECRET>",
  token: "<API_KEY>",
  parameters: [
    {
  		NAME: "<name of the parameter>",
  		VALUE: "<value of the parameter>",
  		TYPE: "<type of parameter: 'text' | 'number' | 'dropdown' | 'boolean' | 'date'>"
    },
		... others parameters
   ]
}

Retrieve App Parameters with Webhook

When a parameter is modified/deleted by the client, this change is synchronized with your application through subscription to the webhook on_app_parameters_changed.

You will then receive the following information in the request body:

{
  parameters: [
    {
  		NAME: "<name of the parameter>",
  		VALUE: "<value of the parameter>",
  		TYPE: "<type of parameter: 'text' | 'number' | 'dropdown' | 'boolean' | 'date'>"
    },
		... others parameters
   ]
}

Retrieve App Parameters by API

App parameters can also be retrieved using Edusign's API :

GET <https://ext.edusign.fr/v1/apps/parameters/:appId>  (Your App Project ID)

Result:

HTTP/1.1 200 OK  
{  
    "status": "success",  
    "result": [  
        {  
            "ID": 6,  
            "APP_ID": "qzqef1eild78wud",  
            "SCHOOL_ID": "vn82hoj9",  
            "NAME": "API Key", // The Name of the parameter  
            "VALUE": "xxx" // The value of the parameter  
        }  
    ]  
}

Updated 5 months ago