.. _private-submission:

Create a Private Submission  
============================
.. admonition:: API Endpoint: submission_create
   
   Creates a new private submission.

.. important:: 
  An API Key is required for ALL private workspace activities
    
  The API Key name component can be added to your header using any of the following ways, "X-CKAN-API-Key", "EDX-API-Key", or "Authorization".



Parameter Definitions
----------------------

.. list-table:: 
   :header-rows: 1

   * - Parameter Name
     - Description
     - Required Fields
   * - ``type``
     - ``type`` must match one of four EDX approved submission types: dataset, tool, publication, presentation
     - **Required**
   * - ``title``
     - Title of the Submission (Human readable - spaces and capitalization are allowed)
     - **Required**
   * - ``name``
     - URL structured name that must be lowercase and alphanumeric - underscores and dashes are allowed
     - **Required**
   * - ``description``
     - Description of the Submission
     - **Required**
   * - ``citation``
     - Citation for the Submission
     - **Required**
   * - ``keywords``
     -  Keywords describing submission. It must be a comma separated string if multiple keywords are listed
     - **Required**
   * - ``netl_product``
     - Determines if submission is a product of NETL funded research
     - **Required**
   * - ``poc_email``
     - NETL Point of Contact email address
     - *Situational* **Required**
   * - ``point_of_contact``
     - First and Last name of NETL Point of Contact
     - *Situational* **Required**
   * - ``program_or_project``
     - NETL Program or Project the Submission is associated with
     - *Situational* **Required**
   * - ``project_number``
     - NETL project/contract number associated with the NETL funded project
     - *Situational* **Required**
   * - ``aiml_product``
     - Determines if submission is an Artificial Intelligence Machine Learning (AIML) product
     - **Required**
   * - ``aiml_submission_types``
     - Submission type associated with the AIML product. 
     - *Situational* **Required**
   * - ``geospatial_product``
     - Determines if submission is a Geospatial product
     - **Required**
   * - ``fgdc_compliant``
     - Determines if Geospatial product is `FGDC Compliant <https://www.fgdc.gov/metadata/geospatial-metadata-tools>`_
     - *Situational* **Required**
   * - ``publication_date``
     -  Date the Submission will be Published. Format yyyy-mm-dd
     - *Optional*
   * - ``restriction_date``
     - Date the submission will be released to the public after approval. Format yyyy-mm-dd
     - *Optional*
   * - ``maintainer``
     -  First and Last name of the Maintainer
     - *Optional*
   * - ``maintainer_email``
     - Email address of the Maintainer
     - *Optional*
   * - ``workspace_id``
     - The name or ID of workspace that you wish to add a Submission to if it is intended for Private use 
     - *Optional*


|

Author Parameter Definitions
-------------------------------

.. list-table:: 
   :header-rows: 1

   * - ``username``
     - field used for entering username for a registered EDX user. See :ref:`Situational Use Cases <situation-case>` and ``username`` in :ref:`Author Field <author-field2>` for more details
     - **Required**
   * - ``fullname``
     - field used for entering the full name for a non-registered EDX user. See :ref:`Situational Use Cases <situation-case>` and ``fullname`` in :ref:`Author Field <author-field2>` for more details
     - **Required**
   * - ``type``
     - field to define the author type for the submission. See :ref:`Situational Use Cases <situation-case>` and ``type`` in :ref:`Author Field <author-field2>` for more details
     - **Required**


|
|

.. _situation-case:

Situational Use Cases 
~~~~~~~~~~~~~~~~~~~~~~
.. note::
   "SITUATIONAL" REQUIRED PARAMETERS ARE ONLY REQUIRED IN SPECIFIC USE CASES.


* If ``netl_product`` is 'yes' the following parameters are required

  * ``poc_email`` is required when "netl_product" parameter field is 'yes'

  * ``point_of_contact`` is required when "netl_product" parameter field is 'yes'

  * ``program_or_project`` is required when "netl_product" parameter field is 'yes'

  * ``project_number`` is required when "netl_product" parameter field is 'yes'


* If ``aiml_product`` product is 'yes' the following parameters are required

  * ``aiml_submission_types`` is required when "*aiml_product*" parameter field is 'yes'


* If ``geospatial_product`` product is 'yes' the following parameters are required

  * ``fgdc_compliant`` is required when "geospatial_product" parameter field is 'yes'

* If the author is a registered EDX user, the first field in the ``Authors`` dictionary will be ``username``

* If the author is **NOT**** a registered EDX user, the first field in the ``Authors`` dictionary will be ``fullname``





EDX Approved Submission types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
   Submission types must match one of four EDX approved submission types.

* dataset
* tool
* publication
* presentation


AIML types
~~~~~~~~~~~~~
.. note::
   The Artificial Intelligence / Machine Learning (AIML) data field must match at least one of five AIML types.

* compiledModel
* trainingData
* gitLinkModel
* aiMethodDoc
* aiResource


Workspace ID Field
~~~~~~~~~~~~~~~~~~~~
* ``workspace_id`` field is required to create a private submission

.. Attention::
    Not including a ``workspace_id`` will create a public submission

.. tip:: 
    *A workspace's id is the text that appears in the address bar, it is* **NOT** *the plain text title found in the body of the website.*
    
    For Example (workspace id),

    **Use** ``sample-edx-workspace`` 
        
    Do **NOT** use ``Sample EDX Workspace``

.. important:: 
   When defining workspace ID, **ONLY** select the end path of the URL

   .. figure:: /images/url-path.png
      :align: center
      :alt: url path image
      :scale: 100 %

|
|

.. _author-field2:

Authors Field
~~~~~~~~~~~~~~~~~~
* Within the ``Authors`` dictionary, there are required fields to add authors to a submission
    * ``username`` : 'edx-author-username'
    * ``fullname`` : 'non-edx-author-full-name'
    * ``type`` : 'author-type'

.. note::
  ``type`` parameter in the ``Authors`` dictionary only accepts specific types for the field
    * 'Author'
    * 'Contact'
    * 'Contributor'

.. note:: 
  The order in which the authors are input into the ``Authors`` dictionary, will be the order that is present on the web submission-test-2025-01-28-14-13-21



|
|


Example 1: Create a New Basic Private Submission with a Registered EDX User as Author
---------------------------------------------------------------------------------------

.. attention:: 
   * Add the ``"User-Agent":`` parameter within the ``headers`` of the API request
   * Set  ``"User-Agent":`` to the value ``"EDX-USER"``

.. important::
    * In ``Authors`` dictionary, the first parameter must be set to ``username`` for this example
    * A Valid EDX username must be entered as the value for the ``username`` parameter

.. tabs:: lang3

    .. code-tab:: python

        import requests

        headers = {
            "EDX-API-Key": 'YOUR_API_KEY_HERE',
            "User-Agent": 'EDX-USER',
            'Content-Type': 'application/json', 
            'Accept':'application/json'
        }

        data = {
            'type': 'SUBMISSION_TYPE_HERE',
            'title': 'TITLE_OF_SUBMISSION',
            'name': 'NAME_HERE',
            'description': 'DESCRIPTION_HERE',
            'citation': 'LIST_CITATIONS_HERE',
            'keywords': 'KEYWORDS_HERE',
            'netl_product': 'YES-OR-NO',
            'aiml_product': 'YES-OR-NO',
            'geospatial_product': 'YES-OR-NO',
            'workspace_id': 'WORKSPACE-ID-HERE'
            #AUTHOR_TYPES: author, contact, contributor
            'authors': [
              {
                'username': 'EDX-AUTHOR-USERNAME',
                'type': 'AUTHOR-TYPE'
              },
            ],
        }

        url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
        r = requests.post(
            url, # URL to API endpoint
            headers=headers, # Headers dictionary
            json=data, # Dictionary of data params
            
        )
        r_json = r.json()
        print (r.json())

    .. code-tab:: output
        :caption: Successful Output
      
        {'help': '/api/3/action/help_show?name=submission_create', 'success': True, 'result': {'id': 'e7097c64-980a-4f23-9271-73b411dd3978', 'authors': [{'id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5',
         'name': 'atticus-finch', 'fullname': 'Atticus Finch', 'type': 'author', 'position': 0}], 'creator_user_id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5',
          'description': 'Repository..', 'keywords': 'Test, Testing, Author-Test', 'name': 'submission-test-2025-01-28-14-13-21', 'maintainer': None,
          'maintainer_email': None, 'metadata_created': '2025-01-28 15:13', 'metadata_modified': '2025-01-28 15:13', 'num_resources': 0, 'workspace_id': None, 
          'package_reviewed': False, 'private': False, 'state': 'draft', 'title': 'Testing Date -2025-01-28-14-13-21', 'type': 'dataset', 'non_edx_authors': [],
          'publication_date': None, 'restriction_date': None, 'netl_product': 'no', 'poc_email': [], 'point_of_contact': None, 'program_or_project': None, 'project_number': None, 
          'aiml_product': 'no', 'aiml_submission_types': None, 'geospatial': 'no', 'fgdc_compliant': None}}

    .. code-tab:: output
        :caption: Failed Output

        {'help': '/api/3/action/help_show?name=submission_create', 'error': {'authors': ['Author type "kljh" is not valid. Allowed author types are: author, contact, or contributor.'], 
        '__type': 'Validation Error'}, 'success': False}
  
|
|

Example 2: Create a New Basic Private Submission with Author who isn't a Registered EDX User
---------------------------------------------------------------------------------------------

.. attention:: 
   * Add the ``"User-Agent":`` parameter within the ``headers`` of the API request
   * Set  ``"User-Agent":`` to the value ``"EDX-USER"``

.. important::
    * In ``Authors`` dictionary, the first parameter must be set to ``fullname`` for this example
    * A Valid first and last name must be entered as the value for the ``fullname`` parameter
        * Example: ``'fullname': 'First Last'``



.. tabs:: lang3

    .. code-tab:: python

        import requests

        headers = {
            "EDX-API-Key": 'YOUR_API_KEY_HERE',
            "User-Agent": 'EDX-USER',
            'Content-Type': 'application/json', 
            'Accept':'application/json'
        }

        data = {
            'type': 'SUBMISSION_TYPE_HERE',
            'title': 'TITLE_OF_SUBMISSION',
            'name': 'NAME_HERE',
            'description': 'DESCRIPTION_HERE',
            'citation': 'LIST_CITATIONS_HERE',
            'keywords': 'KEYWORDS_HERE',
            'netl_product': 'YES-OR-NO',
            'aiml_product': 'YES-OR-NO',
            'geospatial_product': 'YES-OR-NO',
            #AUTHOR_TYPES: author, contact, contributor
            'authors': [
              {
                'fullname': 'NON-EDX-AUTHOR-FULL-NAME',
                'type': 'AUTHOR-TYPE'
              },
            ],
        }

        url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
        r = requests.post(
            url, # URL to API endpoint
            headers=headers, # Headers dictionary
            json=data, # Dictionary of data params
            
        )
        r_json = r.json()
        print (r.json())

    .. code-tab:: output
        :caption: Successful Output
      
        {'help': '/api/3/action/help_show?name=submission_create', 'success': True, 'result': {'id': '0c54fc39-34ee-458e-9a2b-350d55dd71cb', 'authors': [], 
        'creator_user_id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'description': 'Test-Description', 'keywords': 'Test, Testing, Author-Test', 
        'name': 'submission-test-2025-01-28-14-27-44', 'maintainer': None, 'maintainer_email': None, 'metadata_created': '2025-01-28 15:27', 
        'metadata_modified': '2025-01-28 15:27', 'num_resources': 0, 'workspace_id': None, 'package_reviewed': False, 'private': False, 'state': 'draft', 
        'title': 'Testing Date -2025-01-28-14-27-44', 'type': 'dataset', 'non_edx_authors': [{'fullname': 'Scout Finch', 'type': 'contributor', 'position': 0}], 
        'publication_date': None, 'restriction_date': None, 'netl_product': 'no', 'poc_email': [{'fullname': 'Scout Finch', 'type': 'contributor', 'position': 0}], 
        'point_of_contact': None, 'program_or_project': None, 'project_number': None, 'aiml_product': 'no', 'aiml_submission_types': None, 'geospatial': 'no', 
        'fgdc_compliant': None}}


    .. code-tab:: output
        :caption: Failed Output

        {'help': '/api/3/action/help_show?name=submission_create', 'error': {'authors': ['Author type "kljh" is not valid. Allowed author types are: author, contact, or contributor.'], 
        '__type': 'Validation Error'}, 'success': False}

|
|

Example 3: Create a New Basic Private Submission with Multiple Authors (EDX user and non-EDX user)
---------------------------------------------------------------------------------------------------

.. attention:: 
   * Add the ``"User-Agent":`` parameter within the ``headers`` of the API request
   * Set  ``"User-Agent":`` to the value ``"EDX-USER"``

.. important::
    * In ``Authors`` dictionary, the first parameter must be set to ``username`` for Registered EDX users
    * A Valid EDX username must be entered as the value for the ``username`` parameter

.. important::
    * In ``Authors`` dictionary, the first parameter must be set to ``fullname`` for non-EDX users
    * A Valid first and last name must be entered as the value for the ``fullname`` parameter
        * Example: ``'fullname': 'First Last'``

.. tabs:: lang3

    .. code-tab:: python

        import requests

        headers = {
            "EDX-API-Key": 'YOUR_API_KEY_HERE',
            "User-Agent": 'EDX-USER',
            'Content-Type': 'application/json', 
            'Accept':'application/json'
        }

        data = {
            'type': 'SUBMISSION_TYPE_HERE',
            'title': 'TITLE_OF_SUBMISSION',
            'name': 'NAME_HERE',
            'description': 'DESCRIPTION_HERE',
            'citation': 'LIST_CITATIONS_HERE',
            'keywords': 'KEYWORDS_HERE',
            'netl_product': 'YES-OR-NO',
            'aiml_product': 'YES-OR-NO',
            'geospatial_product': 'YES-OR-NO',
            #AUTHOR_TYPES: author, contact, contributor
            'authors': [
              {
                'username': 'EDX-AUTHOR-USERNAME',
                'type': 'AUTHOR-TYPE'
              },
              {
                'fullname': 'NON-EDX-AUTHOR-FULL-NAME',
                'type': 'AUTHOR-TYPE'
              },
            ],
        }

        url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
        r = requests.post(
            url, # URL to API endpoint
            headers=headers, # Headers dictionary
            json=data, # Dictionary of data params
            
        )
        r_json = r.json()
        print (r.json())

    .. code-tab:: output
        :caption: Successful Output
      
        {'help': '/api/3/action/help_show?name=submission_create', 'success': True, 'result': {'id': 'fd095916-7d7b-4e9d-83be-51f7d9e9dafb', 
        'authors': [{'id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'name': 'edx-user', 'fullname': 'EDX User', 'type': 'author', 'position': 0}], 
        'creator_user_id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'description': 'Repository..', 'keywords': 'Test, Testing, Author-Test', 'name': 
        'submission-test-2025-01-28-14-36-09', 'maintainer': None, 'maintainer_email': None, 'metadata_created': '2025-01-28 15:36', 'metadata_modified': 
        '2025-01-28 15:36', 'num_resources': 0, 'workspace_id': None, 'package_reviewed': False, 'private': False, 'state': 'draft', 'title': 
        'Testing Date -2025-01-28-14-36-09', 'type': 'dataset', 'non_edx_authors': [{'fullname': 'Jem Finch', 'type': 'contact', 'position': 1}], 
        'publication_date': None, 'restriction_date': None, 'netl_product': 'no', 'poc_email': [{'fullname': 'Jem Finch', 'type': 'contact', 'position': 1}], 
        'point_of_contact': None, 'program_or_project': None, 'project_number': None, 'aiml_product': 'no', 'aiml_submission_types': None, 'geospatial': 'no', 
        'fgdc_compliant': None}}


    .. code-tab:: output
        :caption: Failed Output

        {'help': '/api/3/action/help_show?name=submission_create', 'error': {'authors': ['No user found with the username Incorrect-Username. If your author does not have an EDX account, provide "fullname" in your request data.'], '__type': 'Validation Error'},
        'success': False}

|
|




Example 4 : Create a New Private Submission with Additional NETL and Geospatial Fields
--------------------------------------------------------------------------------------------

.. attention:: 
   * Add the ``"User-Agent":`` parameter within the ``headers`` of the API request
   * Set  ``"User-Agent":`` to the value ``"EDX-USER"``

.. tabs:: lang3

    .. code-tab:: 
      :caption: Successful Input

        import requests

        headers = {
            "EDX-API-Key": 'YOUR_API_KEY_HERE',
            "User-Agent": 'EDX-USER',
            'Content-Type': 'application/json',
            'Accept':'application/json'
        }

        data = {
            'type': 'dataset', # type must match one of four EDX approved submission types: dataset, tool, publication, presentation. Required
            'title': 'Example Submission', #Required
            'name': 'example-submission', #Must have at least 2 alphanumeric characters. Must be all lowercase and supports underscores and dashes.Required
            'description': 'This is an example.', #Required
            'citation': 'John Smith, Example Submission, 5/24/2024, https://edx.netl.doe.gov/dataset/example-submission', #Required
            'keywords': 'example, example2', #Required. Can be a comma separated string
            'netl_product': 'yes', # If not y, yes, or True, 'True' == no. Required
            'poc_email': 'scout.finch@netl.doe.gov', #required if netl_product is yes. Ignored if netl_product is no or missing. must have @netl.doe.gov or @contr.netl.doe.gov in email
            'point_of_contact': 'Scout Finch', #required if netl_product is yes. Ignored if netl_product is no or missing.
            'program_or_project': 'Geothermal 4D', #required if netl_product is yes. Ignored if netl_product is no or missing.
            'project_number': '1234567', #required if netl_product is yes. Ignored if netl_product is no or missing.
            'aiml_product': 'yes', #If not y, yes, or True, 'True' == no . Required
            'aiml_submission_types': [ "compiledModel", "gitLinkModel", "aiResource" ], #required if aiml_product is yes. Must be an array. Items in list must match one of 5 types.Ignored if aiml_product is no or missing.
            'geospatial_product': 'yes', # If not y, yes, or True, 'True' == no . Required
            'fgdc_compliant': 'no' , # If not y, yes, or True, 'True' == no . Required if geospatial_product is yes. Ignored if geospatial_product is missing.
            'publication_date': '2024-05-24', # format yyyy-mm-dd
            'restriction_date': '2025-01-31', # format yyyy-mm-dd
            'maintainer': 'Jack Horner',
            'maintainer_email': 'jack.horner@netl.doe.gov', # Must be valid email format.
            #AUTHOR_TYPES: author, contact, contributor
            'authors': [
              {
                'username': 'EDX-AUTHOR-USERNAME',
                'type': 'AUTHOR-TYPE'
              },
              {
                'fullname': 'NON-EDX-AUTHOR-FULL-NAME',
                'type': 'AUTHOR-TYPE'
              },
            ],
        }

        url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
        r = requests.post(
            url, # URL to API endpoint
            headers=headers, # Headers dictionary
            json=data, # Dictionary of data params
            
        )
        r_json = r.json()
        print (r.json())

    .. code-tab:: output
        :caption: Successful Output

        {'help': '/api/3/action/help_show?name=submission_create', 'success': True, 'result': {'id': 'c1abbb28-cf51-48bf-98e5-a7f07b5973e3', 
        'authors': [{'id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'name': 'edx-user', 'fullname': 'EDX USER', 'type': 'author', 'position': 0}], 
        'creator_user_id': 'd3083789-6e6c-4e0d-b55d-cf47d6751be5', 'description': 'This is an example.', 'keywords': 'example, example2', 'name': 
        'test-multi-netl-author', 'maintainer': 'Jack Horner', 'maintainer_email': 'jack.horner@netl.doe.gov', 'metadata_created': '2025-01-28 15:46', 
        'metadata_modified': '2025-01-28 15:46', 'num_resources': 0, 'workspace_id': None, 'package_reviewed': False, 'private': False, 'state': 'draft', 
        'title': 'Example Submission', 'type': 'dataset', 'non_edx_authors': [{'fullname': 'Scout Finch', 'type': 'contact', 'position': 1}], 
        'publication_date': '2024-05-24', 'restriction_date': '2025-01-31', 'netl_product': 'yes', 'poc_email': [{'fullname': 'Scout Finch', 'type': 
        'contact', 'position': 1}], 'point_of_contact': 'Scout Finch', 'program_or_project': 'Geothermal 4D', 'project_number': '1234567', 'aiml_product': 
        'yes', 'aiml_submission_types': ['compiledModel', 'gitLinkModel', 'aiResource'], 'geospatial': 'yes', 'fgdc_compliant': None}}


    
    .. code-tab:: output
        :caption: Failed Input

        import requests

        headers = {
            "EDX-API-Key": 'YOUR_API_KEY_HERE',
            "User-Agent": 'EDX-USER',
            'Content-Type': 'application/json',
            'Accept':'application/json'
        }

        data = {
            'type': 'dataset', # type must match one of four EDX approved submission types: dataset, tool, publication, presentation. Required
            'title': 'Example Submission', #Required
            'name': 'example-submission', #Must have at least 2 alphanumeric characters. Must be all lowercase and supports underscores and dashes.Required
            'description': 'This is an example.', #Required
            'citation': 'John Smith, Example Submission, 5/24/2024, https://edx.netl.doe.gov/dataset/example-submission', #Required
            'keywords': 'example, example2', #Required. Can be a comma separated string
            'netl_product': 'yes', # If not y, yes, or True, 'True' == no. Required
            'poc_email': 'scout.finch@example.com', #required if netl_product is yes. Ignored if netl_product is no or missing. must have @netl.doe.gov or @contr.netl.doe.gov in email
            'point_of_contact': 'Scout Finch', #required if netl_product is yes. Ignored if netl_product is no or missing.
            'program_or_project': 'Geothermal 4D', #required if netl_product is yes. Ignored if netl_product is no or missing.
            'project_number': '1234567', #required if netl_product is yes. Ignored if netl_product is no or missing.
            'aiml_product': 'yes', #If not y, yes, or True, 'True' == no . Required
            'aiml_submission_types': [ "compiledModel", "gitLinkModel", "aiResource" ], #required if aiml_product is yes. Must be an array. Items in list must match one of 5 types.Ignored if aiml_product is no or missing.
            'geospatial_product': 'yes', # If not y, yes, or True, 'True' == no . Required
            'fgdc_compliant': 'no' , # If not y, yes, or True, 'True' == no . Required if geospatial_product is yes. Ignored if geospatial_product is missing.
            'publication_date': '2024-05-24', # format yyyy-mm-dd
            'restriction_date': '2025-01-31', # format yyyy-mm-dd
            'maintainer': 'Jack Horner',
            'maintainer_email': 'jack.horner@netl.doe.gov', # Must be valid email format.
            #AUTHOR_TYPES: author, contact, contributor
            'authors': [
              {
                'username': 'EDX-AUTHOR-USERNAME',
                'type': 'AUTHOR-TYPE'
              },
              {
                'fullname': 'NON-EDX-AUTHOR-FULL-NAME',
                'type': 'AUTHOR-TYPE'
              },
            ],
        }

        url = 'https://edx.netl.doe.gov/api/3/action/submission_create'
        r = requests.post(
            url, # URL to API endpoint
            headers=headers, # Headers dictionary
            json=data, # Dictionary of data params
            
        )
        r_json = r.json()
        print (r.json())
      

    
    .. code-tab:: output
        :caption: Failed Output

        {'help': '/api/3/action/help_show?name=submission_create', 'error': {'netl_product': ['poc_email: Your poc_email must have @netl.doe.gov or @contr.netl.doe.gov email address.'], 
        '__type': 'Validation Error'}, 'success': False}