Knowledge Base | apollon

Keywords API

Provides operations on OMN keywords.

Retrieve keywords

/common/keywords/retrieve Returns keywords by specified path.

Table 1. Details
Resource path	/api/core/v1/common/keywords/retrieve
HTTP method	POST
Request content type	application/json
Response content type	application/xml; charset=UTF-8; application/json application/json+compact

Body parameters

Specified by KeywordRequest

path - (String) - Keyword path
level - (Integer) - It defines how many level should be loaded. Default value is 1. -1 means to load all levels. 0 is invalid value
retrieveLinks - (true|false) - It defines whether linked to keyword items should be retrieved or not By default, it is false; (Optional)

Return Type

OmnType with filled KeywordsType

Responses

Table 2. Http response codes
Code	Message	Datatype
200	OmnType with list of keywords	OmnType
400	Invalid input provided	ResponseType
404	The requested resource could not be found	ResponseType
500	An unknown internal error occurred	ResponseType

Samples

Please use transform endpoint to get the JSON/compact-JSON samples from the XML one.

Get a list of all keywords

Request body

{
    "path": "/",
    "level": -1
}

Response body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-11-29T21:55:49.197Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <kwds>
        <kwd id="46190" path="/rootKwd">
            <name>
                <itm>rootKwd</itm>
                <itm loc="en_EN">rootKwd_en</itm>
            </name>
            <meta>
                <itm key="creationDate">2022-06-10T20:07:45.684Z</itm>
                <itm key="orderNumber">0</itm>
            </meta>
        </kwd>
        <kwd id="57210" path="/root2">
            <name>
                <itm>root2</itm>
            </name>
            <meta>
                <itm key="creationDate">2022-07-14T20:05:17.534Z</itm>
                <itm key="orderNumber">0</itm>
            </meta>
        </kwd>
    </kwds>
</pim>

Get a list of child keywords for the specified keyword

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/retrieve' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "path": "/rootKwd",
    "level": 1
}'

Request body

{
    "path": "/rootKwd",
    "level": 1
}

Response body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-11-29T21:56:42.688Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <kwds>
        <kwd id="46190" path="/rootKwd">
            <name>
                <itm>rootKwd</itm>
                <itm loc="en_EN">rootKwd_en</itm>
            </name>
            <meta>
                <itm key="creationDate">2022-06-10T20:07:45.684Z</itm>
                <itm key="orderNumber">0</itm>
            </meta>
        </kwd>
    </kwds>
</pim>

Get a list of keywords with linked assets

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/retrieve' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "path": "/rootKwd",
    "level": 2,
    "retrieveLinks": true
}'

Request body

{
    "path": "/rootKwd",
    "level": 2,
    "retrieveLinks": true
}

Response body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-11-29T21:57:37.832Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <kwds>
        <kwd id="46190" path="/rootKwd">
            <name>
                <itm>rootKwd</itm>
                <itm loc="en_EN">rootKwd_en</itm>
            </name>
            <meta>
                <itm key="creationDate">2022-06-10T20:07:45.684Z</itm>
                <itm key="orderNumber">0</itm>
            </meta>
            <links>
                <itms type="asset">
                    <itm>C150E62E-F9F5-4DF5-B5FB-5AFDC5A3B87C</itm>
                    <itm>0CA65815-03DF-40CA-ACCD-309882B74A36</itm>
                </itms>
            </links>
        </kwd>
        <kwd id="46191"
           parentId="46190"
           path="/rootKwd/subKwd"
           parentPath="/rootKwd">
            <name>
                <itm>subKwd</itm>
            </name>
            <meta>
                <itm key="creationDate">2022-06-10T20:08:13.339Z</itm>
                <itm key="orderNumber">1</itm>
                <itm key="parent">rootKwd</itm>
            </meta>
            <links>
                <itms type="asset">
                    <itm>C150E62E-F9F5-4DF5-B5FB-5AFDC5A3B87C</itm>
                </itms>
            </links>
        </kwd>
    </kwds>
</pim>

Persist keywords

/common/keywords/persist Create or update the keywords

Table 3. Details
Resource path	/api/core/v1/common/keywords/persist
HTTP method	POST
Request content type	application/xml; charset=UTF-8; application/json application/json+compact
Response content type	application/xml; charset=UTF-8; application/json application/json+compact

Body parameters

PimType with filled KeywordsType

Return Type

PimType with filled ResponsesType

Responses

Table 4. Http response codes
Code	Message	Datatype
200	PimType with list of successful or error ResponseTypes	PimType
400	Invalid input provided	ResponseType
500	An unknown internal error occurred	ResponseType

Samples

Please use transform endpoint to get the JSON/compact-JSON samples from the XML one.

Create a root Keyword

Create without specifying path

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/persist' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd>
            <name>
                <itm>rootKeyword</itm>
                <itm loc="en_GB">rootKeyword-en</itm>
                <itm loc="de_DE">rootKeyword-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>'

Request body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd>
            <name>
                <itm>rootKeyword</itm>
                <itm loc="en_GB">rootKeyword-en</itm>
                <itm loc="de_DE">rootKeyword-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>

Create with specifying path

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/persist' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd parentPath="/">
            <name>
                <itm>rootKeyword</itm>
                <itm loc="en_GB">rootKeyword-en</itm>
                <itm loc="de_DE">rootKeyword-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>'

Request body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd parentPath="/">
            <name>
                <itm>rootKeyword</itm>
                <itm loc="en_GB">rootKeyword-en</itm>
                <itm loc="de_DE">rootKeyword-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>

Response body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-06T11:42:19.832Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword" id="52731" action="create" path="/rootKeyword">
            <status>SUCCESS</status>
            <description>The keyword has been created successfully</description>
        </response>
    </responses>
</pim>

Create a sub Keyword

Create under specified path

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/persist' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd parentPath="/rootKeyword">
            <name>
                <itm>keyword1</itm>
                <itm loc="en_GB">keyword1-en</itm>
                <itm loc="de_DE">keyword1-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>'

Request body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd parentPath="/rootKeyword">
            <name>
                <itm>keyword1</itm>
                <itm loc="en_GB">keyword1-en</itm>
                <itm loc="de_DE">keyword1-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>

Create under specified parent keyword

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/persist' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd parentId="12345">
            <name>
                <itm>keyword1</itm>
                <itm loc="en_GB">keyword1-en</itm>
                <itm loc="de_DE">keyword1-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>'

Request body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd parentId="12345">
            <name>
                <itm>keyword1</itm>
                <itm loc="en_GB">keyword1-en</itm>
                <itm loc="de_DE">keyword1-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>

Response body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-06T11:39:54.776Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword"
                id="52730"
                action="create"
                path="/rootKeyword/keyword1">
            <status>SUCCESS</status>
            <description>The keyword has been created successfully</description>
        </response>
    </responses>
</pim>

Update a Keyword

Update by id

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/persist' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd parentId="12345">
            <name>
                <itm>keyword1</itm>
                <itm loc="en_GB">keyword1-en</itm>
                <itm loc="de_DE">keyword1-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>'

Request body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd id="12345">
            <name>
                <itm>keyword1</itm>
                <itm loc="en_GB">new-name-en</itm>
                <itm loc="de_DE">new-name-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>

Update by path

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/persist' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd path="/kwd1/kwd11">
            <name>
                <itm>kwd11</itm>
                <itm loc="en_GB">new-name-en</itm>
                <itm loc="de_DE">new-name-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>'

Request body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <kwds>
        <kwd path="/kwd1/kwd11">
            <name>
                <itm>kwd11</itm>
                <itm loc="en_GB">new-name-en</itm>
                <itm loc="de_DE">new-name-de</itm>
            </name>
        </kwd>
    </kwds>
</pim>

Response body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-06-14T14:34:40.177Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword" id="12345" path="/rootKeyword/new-name-en" action="update">
            <status>SUCCESS</status>
            <description>The keyword has been saved successfully</description>
        </response>
    </responses>
</pim>

Error responses

No keyword by id

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-06T11:45:41.247Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword" id="12345" action="update">
            <status>ERROR</status>
            <description>Entity class com.meylemueller.obj.isy.KeywordEntity with identity=111 not found</description>
        </response>
    </responses>
</pim>

No keyword by path

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-06T11:49:25.214Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword" action="update" path="/rootKeyword">
            <status>ERROR</status>
            <description>No keyword by path '/rootKeyword'</description>
        </response>
    </responses>
</pim>

Keyword is not available for update

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-06T11:50:01.107Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword" id="39400" action="update" path="/Root">
            <status>ERROR</status>
            <description>The keyword is not available by access rights</description>
        </response>
    </responses>
</pim>

Parent keyword is not available

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-06T11:50:27.170Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword" action="create" path="/Root">
            <status>ERROR</status>
            <description>Parent keyword is not available by access rights</description>
        </response>
    </responses>
</pim>

Value is duplicated on the same level

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-07-06T11:51:21.269Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword" action="create">
            <status>ERROR</status>
            <description>Keyword value 'child2-1' for language 'de_DE' is duplicated. Unique keyword values under one parent should be provided</description>
        </response>
    </responses>
</pim>

Perform keywords

/common/keywords/perform Perform actions of the specific type on keywords

Table 5. Details
Resource path	/api/core/v1/common/keywords/perform
HTTP method	POST
Request content type	application/xml; charset=UTF-8; application/json application/json+compact
Response content type	application/xml; charset=UTF-8; application/json application/json+compact

Body parameters

PimType with filled ActionsType

Provided ActionTypes must have the following fields:
- Data type: keyword;
- ID or path of keyword;
- Action type: delete, move, etc.

Return Type

PimType with filled ResponsesType

Responses

Table 6. Http response codes
Code	Message	Datatype
200	PimType with list of successful or error ResponseTypes	PimType
400	Invalid input provided	ResponseType
500	An unknown internal error occurred	ResponseType

Samples

Please use transform endpoint to get the JSON/compact-JSON samples from the XML one.

Delete keyword

Delete by id

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/perform' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <actions>
        <action dataType="keyword" id="73452957" type="delete"/>
    </actions>
</pim>'

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <actions>
        <action dataType="keyword" id="73452957" type="delete"/>
    </actions>
</pim>

Delete by path

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/perform' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <actions>
        <action dataType="keyword" path="/rootKeyword/keyword1" type="delete"/>
    </actions>
</pim>'

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <actions>
        <action dataType="keyword" path="/rootKeyword/keyword1" type="delete"/>
    </actions>
</pim>

Response body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-06-04T13:24:53.286Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword"
                id="73452957"
                path="/rootKeyword/keyword1"
                action="delete">
            <status>SUCCESS</status>
            <description>The keyword has been deleted successfully</description>
        </response>
    </responses>
</pim>

Move keyword to another parent

Move by id

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/perform' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <actions>
        <action dataType="keyword" id="73452957" type="move">
            <meta>
                <itm key="destinationKwdId">73452957</itm>
            </meta>
        </action>
    </actions>
</pim>'

Request body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <actions>
        <action dataType="keyword" id="73452957" type="move">
            <meta>
                <itm key="destinationKwdId">73452957</itm>
            </meta>
        </action>
    </actions>
</pim>

Move by path

curl

curl --location --request POST 'https://<OMN_SERVER>/api/core/v1/common/keywords/perform' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <actions>
        <action dataType="keyword" path="/rootKeyword2/keyword1" type="move">
            <meta>
                <itm key="destinationKwdPath">/rootKeyword</itm>
            </meta>
        </action>
    </actions>
</pim>'

Request body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <actions>
        <action dataType="keyword" path="/rootKeyword2/keyword1" type="move">
            <meta>
                <itm key="destinationKwdPath">/rootKeyword</itm>
            </meta>
        </action>
    </actions>
</pim>

Response body

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-08-17T10:54:57.295Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword"
                id="73452957"
                path="/rootKeyword/keyword1"
                action="move">
            <status>SUCCESS</status>
            <description>keyword has been moved</description>
        </response>
    </responses>
</pim>

Error responses

No keyword by id: Keyword has not been found for provided identity

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-06-04T13:36:54.983Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword"
                id="73452957"
                path="/rootKeyword/keyword1"
                action="delete">
            <status>ERROR</status>
            <description>There is no keyword with the given id</description>
        </response>
    </responses>
</pim>

No access to destination keyword (Move): Access to destination keyword is limited by access rights

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-08-17T10:54:57.295Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword"
                id="73452957"
                path="/rootKeyword/keyword1"
                action="move">
            <status>ERROR</status>
            <description>Error during moving: No access to destination object '/rootKeyword/keyword1'</description>
        </response>
    </responses>
</pim>

No access to keyword: Access to source keyword is limited by access rights

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-08-17T11:06:29.771Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword"
                id="73452957"
                path="/rootKeyword/keyword1"
                action="move">
            <status>ERROR</status>
            <description>Error during moving: No access to source objects</description>
        </response>
    </responses>
</pim>

Wrong data type: Data type is not equal to "keyword"

<?xml version="1.0" encoding="UTF-8"?>
<pim xmlns="http://www.apollon.de/omn" schemaVersion="5.6.0">
    <meta>
        <itm key="messageType">request</itm>
        <itm key="messageTime">2022-06-04T13:38:16.444Z</itm>
        <itm key="sourceEnv">web</itm>
    </meta>
    <responses>
        <response dataType="keyword"
                id="73452957"
                path="/rootKeyword/keyword1"
                action="delete">
            <status>ERROR</status>
            <description>The data type of the passed item is wrong. It must be 'keyword'</description>
        </response>
    </responses>
</pim>

Welcome to the AI Chat!

Write a prompt to get started...