Open Documentation Menu

Configuring the tabs

In the Dashboard section, you can configure up to five tabs for the contract management start page. There are two options for the configuration: editing on the configuration interface and extended configuration in the JSON file. 

Please refer to the following chapters:

Configuring in the configuration interface

This is how it works 

  1. Click New to create a new tab or select an existing tab and click Edit.

  2. In the Name field, enter the name of the tab. The name is displayed on the user interface if no languages are assigned under Title.

  3. Define the title of the tab for the required languages. To do so, select the required language under Language and enter the title under Title. Clicking on Add title for another language adds a new line for configuring the languages.

  4. Under List , select the required list to which the following query refers.

  5. Under Query, define the CAML search that searches the list items. For more information on the CAML search, see https://docs.microsoft.com/en-us with the search term "query schema in CAML".

  6. Under Keyword Query, define the KWQ search that searches the list items. If there are five or more contract lists, it is necessary, due to the high number of contracts, to maintain a keyword query that searches the list items. For more information on the KQL search, see https://docs.microsoft.com/en-us with the search term "syntax reference KQL".

    Note

    To test the keyword query, you can use the URL parameter usekwq=1 on the start page of d.velop contracts for Microsoft 365. The items on the tabs will then be queried using the saved keyword query.

    Example: https://contracts.d-velop365.com/myInstance?usekwq=1

  7. Enter the maximum number of search results under Maximum number of displayed results.

  8. Under Column for sorting, select the column according to which the search results are to be sorted. Under Sorting , define whether the results are to be sorted in ascending or descending order.

  9. Under Columns for viewing, select the columns to be displayed in the result list.

    Note

    Internally, there are two different columns for the date of cancellation and the contract end:

    • Date of cancellation

      • Calculated date of cancellation (ecsNextTermination)

      • Manual date of cancellation (ecsTerminationDate)

    • End of contract

      • Calculated contract end (ecsNextEnd)

      • Manual (fixed) contract end (ecsContractEnd)

    Due to the logic in the application, the two values for the date of cancellation and the contract end date are displayed in a single column in the dashboard as soon as one of the two columns is listed in viewFields. Both columns must be queried when formulating the search.

    Use the following columns for the viewFields list:

    • Date of cancellation: ecsNextTermination

    • Contract end: ecsNextEnd or ecsContractEnd

  10. Click Save.

    Note

    The only way to change the order of the tabs is via the extended configuration in the JSON file.

Extended configuration in the JSON file

The following parameters are available:

  • titles: Create the translations for all languages supported by the application. The translations are applicable for the tabs that you see in the dashboard. Enter the translations as values next to the corresponding language codes. Possible language codes: de, en, fr, it, nl, pt, es, pl.

  • name: This name is only displayed if you have not assigned a title under titles for the corresponding language.

  • relativeListUrl: The relative URL to the list, without the hostname and without the number at the end. (For the example configuration, the lists "ecsContracts0" and "ecsContracts1" are created.)

  • query: A CAML search that searches the list items. For more information on the CAML search, see https://docs.microsoft.com/en-us with the search term "query schema in CAML".

    kwq: If there are five or more contract lists, it is necessary, due to the high number of contracts, to maintain a keyword query that searches the list items. For more information on the KQL search, see https://docs.microsoft.com/en-us with the search term "syntax reference KQL".

    Note

    To test the keyword query, you can use the URL parameter usekwq=1 on the start page of d.velop contracts for Microsoft 365. The items on the tabs will then be queried using the saved keyword query.

    Example: https://contracts.d-velop365.com/myInstance?usekwq=1

  • maxitemcount: Maximum number of search results that will be queried. To ensure a clear display, there is a limit of 100 entries.

  • sortField: Sorting is performed according to this column.

    • name: The internal name of the column

    • ascending: Ascending sorting

  • viewFields: List of the columns to be displayed

    • name: The internal name of the column

    • width (optional): The width of the field.

      Note

      Internally, there are two different columns for the date of cancellation and the contract end:

      • Date of cancellation

        • Calculated date of cancellation (ecsNextTermination)

        • Manual date of cancellation (ecsTerminationDate)

      • End of contract

        • Calculated contract end (ecsNextEnd)

        • Manual (fixed) contract end (ecsContractEnd)

      Due to the logic in the application, the two values for the date of cancellation and the contract end date are displayed in a single column in the dashboard as soon as one of the two columns is listed in viewFields. Both columns must be queried when formulating the search.

      Use the following columns for the viewFields list:

      • Date of cancellation: ecsNextTermination

      • Contract end: ecsNextEnd or ecsContractEnd

Placeholder for the keyword query search

  • Placeholder for user

    • ${User.LoginName}

    • ${User.Title}

    • ${User.Id}

    • ${User.email}

  • Placeholder for dynamic date

    • The first part (Today) indicates that a date can be inserted.

    • The second part (StartOfDay, EndOfDay) indicates that the start or end of the day is to be used.

    • The last part indicates the difference (offset) in days, relative to today’s date.

      • ${Today.StartOfDay.0}

        • Today’s date is: 12/02/2024 12:12

        • This becomes: 2024-12-01T23:00:00.000Z

      • ${Today.StartOfDay.-4}

        • Today’s date is: 12/02/2024 12:12

        • This becomes: 2024-11-27T23:00:00.000Z 

      • ${Today.EndOfDay.92}

        • Today’s date is: 12/02/2024 12:12

        • This becomes 2025-03-04T22:59:59.999Z

      • ${Today.EndOfDay.-2}

        • Today’s date is: 12/02/2024 12:12

        • 2024-11-30T22:59:59.999Z

      • ${Today}

        • Today’s date is 12/02/2024 12:12

        • This becomes 2024-12-02T11:12:00.000Z

  • Placeholder for managed metadata

    • The first part indicates which managed metadata column is to be used. 

    • The second part indicates which taxonomy value is to be used. For this, a local custom property must be configured for the corresponding term (InternalName=value)

      For the column "ecsContractType", the value from "ContentType" is read instead of "internalName". 

    • The last part indicates which property of the term is to be inserted. The following properties are available:

      • termStoreId: ID of the TermStores

      • termSetId: ID of the TermSet

      • wssId: Lookup ID of the term

      • id: ID of the term

      • name: Name of the term

    • Example:

      • ${ecsContractState.Completed.Id}: The ID of the term "Completed" from the "ecsContractState" column would be inserted.

Example of tabs configuration

With the example configuration, for example, the most recently modified contracts are displayed on the start page of d.velop contracts for Microsoft 365 under Last modified.

Example dashboard configuration 

[
    {
        "name": "LastChanged",
        "titles": {
            "de": "Zuletzt geändert",
            "en": "Last modified"
        },
        "relativeListUrl": "/ecsContracts",
        "query": "1",
        "kwq": "EditorOWSUSER:(${User.Title}//${User.LoginName}*) AND ContentTypeId:0x0120D52000A01E1DFC8CA3644A839475A34955DDEE* AND IsContainer:true",
        "sortField": {
            "name": "Modified",
            "ascending": false
        },
        "viewFields": [
            {
                "name": "ecsSubjectOfContract"
            },
            {
                "name": "ecsCPLookup"
            },
            {
                "name": "ecsContractType"
            },
            {
                "name": "ecsContractState"
            },
            {
                "name": "Modified",
                "width": 120
            }
        ],
        "maxitemcount": 25
    },
    {
        "name": "UpcomingDeadlines",
        "titles": {
            "de": "Anstehende Fristen",
            "en": "Upcoming Deadlines"
        },
        "relativeListUrl": "/ecsContracts",
           "query": "101",
           "kwq": "ecsResponsibleOWSUSER:(${User.Title}//${User.LoginName}*) AND ContentTypeId:0x0120D52000A01E1DFC8CA3644A839475A34955DDEE* AND IsContainer:true AND (RefinableDate06>=${Today.StartOfDay.0} AND RefinableDate06<=${Today.EndOfDay.92})",
           "sortField": {
               "name": "ecsNextTermination"
           },
           "viewFields": [                  {
                   "name": "ecsSubjectOfContract"
               },
               {
                   "name": "ecsContractType"
               },
               {
                   "name": "ecsCPLookup"
               },
               {
                   "name": "Modified",
                   "width": 120
               },
               {
                   "name": "ecsNextTermination",
                   "width": 120
               }
            ],
           "maxitemcount": 25
    },
    {
        "name": "MyTasks",
        "titles": {
            "de": "Meine Aufgaben",
            "en": "My tasks"
        },
        "relativeListUrl": "/Lists/ecsTasks",
        "query": "0${ecsTaskState.Completed.WSSId}",
        "kwq": "ecsResponsibleOWSUSER:(${User.Title}//${User.LoginName}*) AND IsContainer=false AND ContentTypeId:0x0100B252310F71CBCE46B259C77B2ECA5D69* AND (NOT owstaxIdecsTaskState:#${ecsTaskState.Completed.Id}|*)",
        "sortField": {
            "name": "ecsTaskDueDate",
            "ascending": true
        },
        "viewFields": [
            {
                "name": "ecsSubjectOfContract",
                "width": 120
            },
            {
                "name": "ecsCPLookup"
            },
            {
                "name": "ecsContractType"
            },
            {
                "name": "Title"
            },
            {
                "name": "ecsTaskDueDate",
                "width": 120
            },
            {
                "name": "ecsTaskState"
            }
        ],
        "maxitemcount": 50
    },
    {
        "name": "MyTasksDelegated",
        "titles": {
            "de": "Meine delegierten Aufgaben",
            "en": "My delegated tasks"
        },
        "relativeListUrl": "/Lists/ecsTasks",
        "query": "0${ecsTaskState.Completed.WSSId}",
        "kwq": "IsContainer=false AND ContentTypeId:0x0100B252310F71CBCE46B259C77B2ECA5D69* AND AuthorOWSUSER:(${User.Title}//${User.LoginName}*) AND (NOT owstaxIdecsTaskState:#${ecsTaskState.Completed.Id}|*) AND (NOT ecsResponsibleOWSUSER:(${User.Title}//${User.LoginName}*))",
        "sortField": {
            "name": "ecsTaskDueDate",
            "ascending": true
        },
        "viewFields": [
            {
                "name": "ecsSubjectOfContract",
                "width": 120
            },
            {
                "name": "ecsCPLookup"
            },
            {
                "name": "ecsContractType"
            },
            {
                "name": "Title"
            },
            {
                "name": "ecsTaskState"
            },
            {
                "name": "Created",
                "width": 120
            },
            {
                "name": "Modified",
                "width": 120
            },
            {
                "name": "ecsTaskDueDate",
                "width": 120
            },
            {
                "name": "ecsResponsible"
            }
        ],
        "maxitemcount": 50
    },
    {
        "name": "NoDocs",
        "titles": {
            "de": "Unvollständige Verträge",
            "en": "Incomplete Contracts"
        },
        "relativeListUrl": "/ecsContracts",
        "query": "1${ecsContractState.Canceled.WSSId}${ecsContractState.Expired.WSSId}",
        "kwq": "ContentTypeId:0x0120D52000A01E1DFC8CA3644A839475A34955DDEE* AND IsContainer:true AND AuthorOWSUSER:(${User.Title}//${User.LoginName}*) AND (NOT owstaxIdecsContractState:#${ecsContractState.Canceled.Id}|*) AND (NOT owstaxIdecsContractState:#${ecsContractState.Expired.Id}|*) OR (owstaxIdecsContractState:#${ecsContractState.Draft.Id}|* OR (NOT RefinableDate02:1900-01-01..3000-12-31) OR (NOT owstaxIdecsContainingDocumentTypes:*) OR (NOT ecsSubjectOfContractOWSTEXT:*) OR (NOT ecsCPLookup:*) OR (NOT owstaxIdecsContractOrganization:*) OR (NOT ecsResponsibleOWSUSER:*))",
        "viewFields": [
            {
                "name": "ecsSubjectOfContract"
            },
            {
                "name": "ecsCPLookup"
            },
            {
                "name": "ecsContractType"
            },
            {
                "name": "ecsResponsible"
            },
            {
                "name": "ecsContractState"
            },
            {
                "name": "ecsContractStart",
                "width": 120
            },
            {
                "name": "Modified",
                "width": 120
            }
        ],
        "sortField": {
            "name": "Modified",
            "ascending": true
        },
        "maxitemcount": 50
    }
]