Categories CSV - Usage and Schema Description

Printer-friendly version

Categories CSV

The Categories CSV may be used for creating, updating or deletion of, a large amount of categories.

Purpose and Usage

The categories CSV for bulk operation may be useful for:

  • Creating multiple categories for any applicative use. For example:
  • Creating multiple categories for the initial setup of Media Space’s galleries and channels
  • Creating multiple categories for a Kaltura based website integration
  • An on-going scheduled process for the syncing categories managed in Kaltura with a respective external structure. For example:
  • A scheduled daily sync process for syncing MediaSpace group channels with groups managed in the organization.
  • An automatic sync of Kaltura’s categories with the taxonomy of an external CMS 

 

NOTE:  

For an efficient on-going CSV based sync processes, only new categories and categories that require updating or deletion should be included within the CSV

 

NOTE:  

Content entitlement related attributes can be populated via the CSV only in accounts that are set to support entitlements and for categories under a category tree branch that is set to have entitlement settings.

General Guidelines

  • Lines that begin with a # character will not be processed.
  • The first line for processing (fields’ definition line) should start with an * sign and should include the field names to be populated via the CSV, according to the defined schema of each CSV format. Mandatory fields must be present. The field order may be set as needed.
  • Each line for processing within the CSV should include a comma separated list of values ordered by the field ordering set in the fields’ definition line.
  • Each line for processing within the CSV will apply an action on a single Kaltura object. For example: each line in the categories CSV will apply the action to a single category.  
  • The CSV may be submitted from the KMC (through the Upload menu) or via a script, by utilizing Kaltura’s API.
  • Prior to processing the CSV file, its format is validated. When a mandatory field is missing, the bulk job will fail and processing will not start.
  • Bulk job tracking as well as downloading bulk job related files (the original CSV and log files) are done through the KMC using the Bulk Upload Log feature under the Upload Control page.
  • Email notifications on the completion of bulk upload processing - including completion status and a direct link to the log file, can be configured by Kaltura per request.
  • There is no limitation on the supported number of lines within each CSV.  The overall processing time of each CSV file is affected by the number of lines included in it. 
  • The following special characters can be populated within text fields via the CSV file :

           - _ % ? . :  ;  &  > @ ! $ ^ ~  = [ ] { } |  < 

        See special exceptions within each schema description.

The CSV examples included in this guide are displayed in screens from MS Excel for better clarity.

Schema Description for Categories CSV

Parameter Name

Mandatory/ Optional

Description

 

Default

 

Type and Restrictions

action

Optional

Kaltura’s numeric value for the action to apply on a specific category.

CSV lines with different actions can be combined into a single CSV file. Only fields that are relevant to the CSV action will be used.

The supported action types and their numeric values are:

1=Add - to add a category

2=Update – to update an existing category

3=Delete – to delete an existing category

6=Add or Update – to add or update a category when the given categoryId or referenceId are already available in Kaltura.

1= Add

KalturaBulkUploadAction

name

Mandatory in add actions

The name of the category. When the category name includes the > character it will automatically be replaced with _ (underscore character).

 

Text Field. Maximum length: 60 Characters

relativePath

Optional

The category-tree path in which the category is located or should be created. Each category level within the path should be separated by the ‘> ‘character.  

Note: The provided path must exist prior to processing  the CSV line, or created in a higher CSV line.

 

Text Field. Unlimited length

categoryId

Optional

The Kaltura internal and unique identifier of the category.  The categoryId field is used in the CSV for identifying a category that requires updating or needs to be deleted.

In an ‘update’ or a ‘delete’ action, either the categoryId or the referenceId field must be provided for identifying the category to which the action should apply.

In ‘add’ actions the categoryId field will be ignored.

 

Integer 

referenceId

Optional

A possible identifier of the category based on an identifier from an external system that can relate the category to an external entity it represents or related to.

In an ‘update’ or a ‘delete’ action, either the categoryId or the referenceId field must be provided for identifying the category to which the action should apply.

In ‘add’ actions the referenceId will be populated into the new category.

Note: The uniqueness of the referenceId field is not verified nor managed in Kaltura.  It is recommended to use logic that maintains this uniqueness for being able to reference bulk actions and API calls to a specific category.

In case multiple categories with the same referenceId exist in the account, any update/delete action will be committed only to a single category.

 

Text Field. Maximum length: 512 Characters

tags

Optional

The tags to be added to the category. Multiple tags can be separated by commas, while the entire field should be wrapped with double quotation marks (e.g. “tag1, tag2). When the CSV is created in a simple text editor or by a script - the wrapping quotation marks should be added explicitly.  When CSV is created with a spread sheet editor (e.g. MS Excel) this wrapping is automatically generated when saving to a CSV format with no need for manual editing.

Tag values cannot include commas.

 

Text Field. Unlimited length

description

Optional

A description of the category and its applicative/administrative purpose.

When the CSV is created in a simple text editor or by a script – adding wrapping quotation marks is recommended for cases in which the description includes commas

 

Text Field. Unlimited length

Custom Data

 

Custom data fields that are set to extend the Kaltura Category object can be populated into a category by defining the fields in the following formats:

metadata::the-schema-system-name::the-schema-field-name

With this format multiple custom data schemas and fields can be populated via the CSV.

Custom data schema and fields system names are available in the custom data setting page in the KMC.

Values of custom data fields that have multiple values should be separated with a the following delimiter:   |,|

Note: When updating custom data fields to an existing category, a new metadata XML is automatically created. For preventing overriding existing values, all custom data fields that are set for the user should be provided in the CSV as part of the update action.

 

 

Entitlements Settings

privacy

Optional

The numeric value of the Content Privacy option to set for the category as part of its entitlements settings.

This option is enabled only in accounts that are configured to support end-user entitlements to content and for categories that were set to have entitlement settings.

The supported action types and their numeric values are:

1= No Restriction

2 =Requires Authentication

3= Private

1 = No Restriction

KalturaPrivacyType

appearInList

Optional

The numeric value of the Category Listing option to set for the category as part of its entitlements settings.

The setting of this option is enabled only in accounts that were configured to support Content Entitlements and in categories that have entitlement settings.

The supported action types and their numeric values are:

1= No Restriction

3= Private

1 = No Restriction

KalturaAppearInListType

contributionPolicy

Optional

The numeric value of the ContributionPolicy option (who can add content to the category) to set for the category as part of its entitlements settings.

The setting of this option is enabled only in accounts that were configured to support Content Entitlements and in categories that have entitlement settings.

The supported action types and their numeric values are:

1= No Restriction

2= Private

1 = No Restriction

KalturaContributionPolicyType

inheritanceType

Optional

The numeric value of user permissions inheritance option (Inherit End-User Specific Permissions from Parent Category) to set for the category as part of its entitlements settings.

The setting of this option is enabled only in accounts that were configured to support Content Entitlements and in categories that have entitlement settings.

The supported action types and their numeric values are:

1= Yes.  inherit specific end-user permissions from  parent category

3= No.

2=No

KalturaInheritanceType

owner

Optional

The userId of the category's owner.

 

Text Field.

Minimum length: 3 characters Maximum length: 100 Characters

Only the following special characters are supported as part of the userId:

. _ @ -

 

defaultPermissionLevel

Optional

The numeric value of the default permission Level the end-users should be granted for the specific category (unless other permission level was specified explicitly via CSV or API). The supported values are:

0=Manager

1=Moderator

2=Contributor

3=Member

3=Member

KalturaCategoryUserPermissionLevel

moderation

Optional

Indicates whether content should be moderated in the application before it is added to the category.

0=moderation is not required

Boolean

Examples of the Categories CSV

Bulk Creation of Categories – Basic Metadata Only

Updating Existing Categories with a Few Entitlement Settings

This example uses the referenceId as the category identifier.

(12659 reads)