edoc contract Administration Guide
edoc contract Administration Guide
Breadcrumbs

Create a reminder with the REST API

In this topic, you will learn how to create a reminder using the web service endpoint. The required reminder data is transferred to the web service endpoint as a JSON object using the POST method.

An API key is required for authentication at the web service endpoint. You must adjust the API key in edoc automate before deploying and releasing the app.

How to customize the API key in edoc automate

  1. In edoc automate, go to App details in the navigation bar and open the app variables in the workspace.

  2. Replace the value of the variable rest_api.reminder_create.api_key with a new API key.

Use the header name edoc-contract-secret for the connection.

Use the following URL to call up the web service endpoint for creating a reminder: https://<app-server>/apps/ws/edoc-contract/createReminder

Replace the placeholder <app-server> with the name of the server on which edoc automate is running.

Things to know about date fields

Regardless of which reminder type you want to create, you must always enter dates in ISO format YYYY-MM-DD (e.g.: 2023-11-24).

Default parameters of the JSON object for different reminder types

The JSON object looks different for the different reminder types. There is a range of information that you must specify for each JSON object by default.

You must always transfer the following data, regardless of the reminder type:

  • ecm_id: specify the unique ID of the contract in the ECM system.

  • reminder_type: specify the numerical value for the reminder type:

    • 1 is the value for a task.

    • 2 is the value for a termination.

    • 3 is the value for single renewal.

    • 5 is the value for a guarantee.

    • 6 is the value for a recurring renewal.

  • reminder_note: enter a note for the reminder if required.

  • reminder_date: specify the date (YYYY-MM-DD) for the reminder.

  • reminder_recipients: specify the technical names of the recipients separated by commas.

  • creator: specify the technical name of the creator of the reminder.

  • switch_notification_done_activate: enter the numerical value to activate the e-mail notification when a task is completed:

    • 1 means that the notification is activated.

    • 2 means that the notification is deactivated.

  • recipients_notification_done: specify the technical names of the recipients, separated by commas, who should receive an e-mail notification when a task is completed.

  • switch_notification_creator_activate: specify the numerical value to activate the e-mail notification for the creator of the reminder:

    • 1 means that the notification to the creator is activated.

    • 2 means that the notification to the creator is deactivated.

Parameters for a simple task (reminder type 1)

In addition to the data that you must enter by default, you must also enter the following parameters for a simple task:

  • task_periodical_active: specify the numerical value 0 to create a simple task.

Example of a JSON object for a simple task:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "1",
	"reminder_note": "Create simple task",
	"reminder_date": "2023-11-24",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",
    "switch_notification_creator_activate": 1,
	"task_periodical_active": "0"
}

Parameters for a recurring task (reminder type 1)

In addition to the data that you must enter by default, you must also enter the following parameters for a recurring task:

  • task_periodical_active: specify the numerical value 1 to create a recurring task.

  • task_unit: specify a numerical value for the unit of the repetition. The parameter corresponds to the Unit input field on the Reminder page. The following options are available:

    • 1 corresponds to the unit of measurement "day".

    • 2 corresponds to the unit of measurement "week".

    • 3 corresponds to the unit of measurement "month".

    • 4 corresponds to the unit of measurement "year".

  • task_count: specify the numerical value for the time interval of the repetition. The parameter corresponds to the Time interval input field on the Reminder page.

  • task_period_count: specify the number of repetitions for the recurring task. The parameter corresponds to the Number of repetitions input field on the Reminder page.

  • task_period_unlimited: specify a numerical value for the unlimited runtime:

    • 0 corresponds to the limited term.

    • 1 corresponds to the unlimited term.

  • task_start: specify the start date (YYYY-MM-DD) for the recurring task. The parameter corresponds to the Start date input field on the Reminder page.

Example of a JSON object for a recurring task:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "1",
	"reminder_note": "Create recurring task",
	"reminder_date": "2023-11-24",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",  
    "switch_notification_creator_activate": 1,
	"task_periodical_active": "1",
	"task_unit": "1",
	"task_count": "5",
	"task_period_count": "4",
	"task_period_unlimited" : "1",
	"task_start": "2023-11-24"
}

Parameters for a termination (reminder type 2)

In addition to the data that you must specify by default, you must also enter the following parameters for a termination:

  • notice_period_count: specify the number of units for the notice period. The parameter corresponds to the Notice period input field on the Reminder page.

  • notice_period_unit: specify the numerical value for the unit of the notice period. The parameter corresponds to the Unit of notice period input field on the Reminder page. The following options are available:

    • 1 corresponds to the unit of measurement "day".

    • 2 corresponds to the unit of measurement "week".

    • 3 corresponds to the unit of measurement "month".

    • 4 corresponds to the unit of measurement "year".

  • notice_period_end: specify the date of the deadline (YYYY-MM-DD). The parameter corresponds to the input field Notice period end date on the reminder form.

  • notice_period_rhythm: specify the numerical value at which the termination should be sent. The parameter corresponds to the By rhythm input field on the Reminder page. The following options are available:

    • 1 corresponds to the end of the contract.

    • 2 corresponds to the end of the month.

    • 3 corresponds to the end of the quarter.

    • 4 corresponds to the end of the year.

  • notice_period_new_contract_end: specify the termination date (YYYY-MM-DD). The parameter corresponds to the Date of termination input field on the Reminder page.

Example of a JSON object for a termination:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "2",
	"reminder_id": null,
	"reminder_note": "Create a termination",
	"reminder_date": "2023-12-24",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",
    "switch_notification_creator_activate": 1,
	"notice_period_count": "4",
	"notice_period_unit": "2",
	"notice_period_end": "2024-01-07",
	"notice_period_rhythm": "1",
	"notice_period_new_contract_end": "2024-02-04"
}

Parameters for a simple extension (reminder type 3)

In addition to the data that you must enter by default, you must also enter the following parameters for a simple renewal:

  • runtime_renewal_count: specify the number of units of a term. The parameter corresponds to the Renewal of term input field on the Reminder page.

  • runtime_renewal_unit: specify the numerical value for the unit of the renewal. The parameter corresponds to the Unit of term input field on the Reminder page. The following options are available:

    • 1 corresponds to the unit of measurement "day".

    • 2 corresponds to the unit of measurement "week".

    • 3 corresponds to the unit of measurement "month".

    • 4 corresponds to the unit of measurement "year".

  • runtime_renewal_end: specify the date for the end of the renewal (YYYY-MM-DD). The parameter corresponds to the End of renewal input field on the Reminder page.

Example of a JSON object for a simple renewal:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "3",
	"reminder_note": "Create simple renewal",
	"reminder_date": "2024-01-28",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",
    "switch_notification_creator_activate": 1,
	"runtime_renewal_count": "1",
	"runtime_renewal_unit": "2",
	"runtime_renewal_end": "2024-02-11"
}

Parameters for a guarantee (reminder type 5)

In addition to the data that you must enter by default, you must also enter the following parameters for a guarantee:

  • guarantee_start: specify the date for the start of the guarantee period (YYYY-MM-DD). The parameter corresponds to the Start of guarantee input field on the Reminder page.

  • guarantee_end: Enter the date for the end of the guarantee period (YYYY-MM-DD). The parameter corresponds to the End of guarantee input field on the Reminder page.

Example of a JSON object for a guarantee:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "5",
	"reminder_note": "Test - Create guarantee using API",
	"reminder_date": "2023-11-24",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",
    "switch_notification_creator_activate": 1,
	"guarantee_start": "2023-11-25",
	"guarantee_end": "2023-12-08"
}

Parameters for an unlimited recurring renewal (reminder type 6)

In addition to the data that you must enter by default, you must also enter the following parameters for an unlimited, recurring renewal:

  • runtime_renewal_count: specify the number of units for the term. The parameter corresponds to the Renewal of term input field on the Reminder page.

  • runtime_renewal_unit: specify the numerical value for the unit of renewal. The parameter corresponds to the Unit of term input field on the Reminder page. The following options are available:

    • 1 corresponds to the unit of measurement "day".

    • 2 corresponds to the unit of measurement "week".

    • 3 corresponds to the unit of measurement "month".

    • 4 corresponds to the unit of measurement "year".

  • runtime_renewal_end: specify the date for the end of the renewal (YYYY-MM-DD). The parameter corresponds to the End of renewal input field on the Reminder page.

  • running_runtime_renewal_unlimited: specify the value 1 for a renewal with an unlimited total term. The parameter corresponds to the Unlimited total term input field on the Reminder page.

Example of a JSON object for an unlimited total term of a contract:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "6",
	"reminder_note": "Create recurring renewal with unlimited total term",
	"reminder_date": "2024-01-26",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",
    "switch_notification_creator_activate": 1,
	"runtime_renewal_count": "5",
	"runtime_renewal_unit": "1",
	"runtime_renewal_end": "2024-02-09",
	"running_runtime_renewal_unlimited": "1"
}

Parameters for a limited recurring renewal (reminder type 6)

You can create a recurring renewal with a time limit using reminder type 6.

In addition to the data that you must enter by default, you must also enter the following parameters for a limited, recurring renewal:

  • runtime_renewal_count: specify the number of units of a term. The parameter corresponds to the Renewal of term input field on the Reminder page.

  • runtime_renewal_unit: specify the numerical value for the unit of the renewal. The parameter corresponds to the Unit of term input field on the Reminder page. The following options are available:

    • 1 corresponds to the unit of measurement "day".

    • 2 corresponds to the unit of measurement "week".

    • 3 corresponds to the unit of measurement "month".

    • 4 corresponds to the unit of measurement "year".

  • runtime_renewal_end: specify the date for the end of the renewal (YYYY-MM-DD). The parameter corresponds to the End of renewal input field on the Reminder page.

  • running_runtime_renewal_unlimited: specify the value 0 for a renewal with a limited total term. The parameter corresponds to the input field. The parameter corresponds to the Unlimited total term input field on the Reminder page.

  • running_runtime_renewal_count: specify the number of units for the Unit of total term parameter. The parameter corresponds to the Total term - number of unit input field on the Reminder page.

  • running_runtime_renewal_unit: specify the numerical value for the unit of the total term. The parameter corresponds to the Unit of total runtime input field on the Reminder page. The following options are available:

    • 1 corresponds to the unit of measurement "day".

    • 2 corresponds to the unit of measurement "week".

    • 3 corresponds to the unit of measurement "month".

    • 4 corresponds to the unit of measurement "year".

  • running_runtime_renewal_end: specify the end date of the recurring renewal (YYYY-MM-DD). The parameter corresponds to the End of total term input field on the Reminder page.

Example of a JSON object time-limited recurring renewal of a contract:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "6",
	"reminder_note": "Create recurring renewal with fixed term",
	"reminder_date": "2024-01-26",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",
    "switch_notification_creator_activate": 1,
	"runtime_renewal_count": "5",
	"runtime_renewal_unit": "1",
	"runtime_renewal_end": "2024-02-09",
	"running_runtime_renewal_unlimited": "0",
	"running_runtime_renewal_count": "3",
	"running_runtime_renewal_unit": "2",
	"running_runtime_renewal_end": "2024-02-25"
}

Parameters for an escalation notification

If you want to generate an escalation notification for the reminder when creating a reminder, enter the following parameters in addition to the parameters for the reminder:

  • reminder_escalation_is_active: specify the numerical value to activate the e-mail notification when a task is escalated:

    • 1 means that the notification has been activated.

    • 2 means that the notification has been deactivated.

  • reminder_escalation_recipients: specify the technical names of the recipients (person, group) who should receive an e-mail notification when a task is escalated, separated by a comma.

  • reminder_escalation_days: specify the number of days until escalation relative to the reminder date.

  • reminder_escalation_days_toggle: specify the correct time period that calculates the actual date based on the number of days specified in the reminder date:

    • 0 means calculate the time period in days before the reminder date.

    • 1 means calculate the time period in days after the reminder date.

Example of a JSON object for a simple task with an escalation:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "1",
	"reminder_note": "Create recurring task",
	"reminder_date": "2023-11-24",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",
    "switch_notification_creator_activate": 1,
	"task_periodical_active": "1",
	"task_unit": "1",
	"task_count": "5",
	"task_period_count": "4",
	"task_period_unlimited" : "1",
	"task_start": "2023-11-24",
	"reminder_escalation_is_active": 1,
    "reminder_escalation_recipients": "<Name>@test.de",
    "reminder_escalation_days": 0,
	"reminder_escalation_days_toggle": 0
}

Parameters for the priority

If you want to specify the priority when creating a reminder, enter the following parameter in addition to the parameters for the reminder:

  • reminder_priority: specify the numerical value for the priority:

    • 0 means that the priority is Default.

    • 1 means that the priority is High.

    • 2 means that the priority is Low.

If you do not specify a priority, it is automatically set to Default.

Example of a JSON object for a simple task with a priority:

JSON
{
	"ecm_id": "A000000009",
	"reminder_type": "1",
	"reminder_note": "Create recurring task",
	"reminder_date": "2023-11-24",
	"reminder_recipients": "admin,<Name>@test.de",
	"creator": "admin",
	"switch_notification_done_activate": "1",
    "recipients_notification_done": "admin,<Name>@test.de",
    "switch_notification_creator_activate": 1,
	"task_periodical_active": "1",
	"task_unit": "1",
	"task_count": "5",
	"task_period_count": "4",
	"task_period_unlimited" : "1",
	"task_start": "2023-11-24",
	"reminder_escalation_is_active": 1,
    "reminder_escalation_recipients": "<Name>@test.de",
    "reminder_escalation_days": 0,
	"reminder_escalation_days_toggle": 0,
    "reminder_priority": 2
}