Define an extraction

  1. Manage files
  2. Create a definition file
  3. Edit extraction description
  4. Modifying a definition file
    1. Create a thesaurus component
    2. Creating a query component
    3. Create a counter component
    4. Create a correspondence table component
    5. The clauses
    6. Add clause variables
    7. Add variables for optional columns
    8. Modifying a node
    9. Delete a node
    10. Save or cancel changes
  5. Rename a definition file
  6. Delete a definition file
  7. Actions to share extractions
    1. Before version 1.7.0
      1. Extraction rights
      2. Tool
      3. Actions
    2. From version 1.7.0

Manage files

Extractions can be saved in folders or subfolders. 

The buttons in the "Folder" category are available: 

  • creates a new folder under the selected node
  • Actions Rename Delete and are also available.

Create a definition file

In the 'Extractions' tab, after selecting a folder, click on the 'New' button:

Renseignez le nom du fichier de définition, un nouveau fichier est créé dans le répertoire WEB-INF/param/extraction/definitions/<Dossier>.

The 'Extraction details' tool opens, showing the root of the tree and the nodes for defining clause variables and optional columns.

You can now create the components for your extraction.

Edit extraction description

In the 'Extractions' tab, click on the 'Modify description' button:

The content modification tool opens, allowing you to modify the extraction description.

Modifying a definition file

Create a thesaurus component

In the 'Extraction details' tool, select a node and click on the 'Thesaurus' button in the 'Extractions' tab:

A dialog box appears, allowing you to enter the information required to create a thesaurus component:

  • Tag name: You can choose the name of the XML element that will be created in the results file for this component. This name must comply with the naming rules for XML elements. Only certain characters are allowed, such as letters, numbers, hyphens, etc. This field is not mandatory; if it is not filled in, the term 'thesaurus' will be used.
  • Thesaurus: Drop-down list of available thesauri. Choose the thesaurus on which to search for terms. This field is mandatory.
  • Microthesarus: Drop-down list with the names of the microthesaurii available for the chosen thesaurus. Select the microthesaurus on which to search for terms. If you change thesaurus, this field is reset. This field is mandatory.
  • Maximum level: Maximum depth at which to search for specific terms. Top-down autoposting will bring up content corresponding to specific terms at lower levels.

A Thesaurus node is created in the tree, below the selected node.

Creating a query component

In the 'Extraction details' tool, select a node and click on the 'Query' button in the 'Extractions' tab:

A dialog box appears, allowing you to enter the information required to create a query component:

  • Tag name: You can choose the name of the XML element that will be created in the results file for this component. This name must comply with the naming rules for XML elements. Only certain characters are allowed, such as letters, numbers, hyphens, etc. This field is not mandatory; if it is not filled in, the term 'query' will be used.
  • Clauses: Text field containing a query solr. You can enter multiple queries by clicking on the '+' button. For more information, see Clauses.
  • Groups : You can choose to group the results of a query according to the content fields retrieved. Fields are separated by commas. Autocomplete will allow you to fill in the fields available for the selected content types.
  • Query type: Specify whether you want to use a saved query or create the query from scratch.

Depending on the type of query selected, new information must be entered:

If you wish to use a saved query :

  • Saved queries: Drop-down list of available saved queries.
  • Column usage: You can choose to use only the columns defined by the saved query, override these columns or add columns to those in the saved query.

  • Columns: Indicate which fields should appear in the results file for this component. Fields are separated by commas. To make a column optional, enter in brackets the name of the variable on which the column display depends. Example:

    metadata_A (optianalA),metadata_B

    See how to create variables for optional columns. Autocomplete will allow you to fill in the fields available for the selected content types.

  • Use sorting: You can choose to use only the sorting defined by the saved query, override this sorting or add fields following those in the saved query.

  • Sorting: Indicate the fields on which to sort the results. Fields are separated by commas. By default, sorting is ascending. You can enter the order in brackets. Example:

    metadata_A (DESC),metadata_B (ASC), metadata_C

If you wish to create a query from scratch :

  • Content types: Tree containing available content types. You can select multiple content types. This field is mandatory.

  • Columns: Indicate which fields should appear in the results file for this component. Fields are separated by commas. To make a column optional, enter in brackets the name of the variable on which the column display depends. Example:

    attribute_A (optianalA), attribute_B

  • Sorting: Indicate the fields on which to sort the results. Fields are separated by commas. By default, sorting is ascending. You can enter the order in brackets. Example:

    attribute_A (DESC), attribute_B (ASC), attribute_C

 

 


A Request node is created in the tree, below the selected node.

Create a counter component

In the 'Extraction details' tool, select a node and click on the 'Counter' button in the 'Extractions' tab:

A dialog box appears, allowing you to enter the information required to create a counter component.

A counter component corresponds to a query component. The parameters to be entered are essentially the same.

The difference lies in the fact that for a counter component, only the number of contents returned by the query is returned. No column or sorting parameters are requested.

A Counter node is created in the tree, below the selected node.

Create a correspondence table component

In the 'Extraction details' tool, select a node and click on the 'Match query' button in the 'Extractions' tab:

A dialog box appears, allowing you to enter the information required to create a correspondence request component.

A match request component corresponds to a query component. The parameters to be entered are essentially the same.

The difference is that the contents returned by a match request component are not displayed. The match request is invisible. As a result, no group, column or sort parameters are requested. The tag name parameter is not requested either.

A Match query node is created in the tree, below the selected node.

 

The clauses

For join solr, always put quotation marks around the q=.

A clause can contain variables defined in another node of the tree. See adding clause variables. The variable name is enclosed in braces, preceded by the '$' sign. Example:

${le_nom_de_ma_variable}

A clause can also be used to join parent components. The link to the parent component is enclosed in braces, preceded by the '$' sign. Use the notation '..' to link to the direct parent. To go back to more distant parents, use "../" as many times as necessary. You can also specify the name of an attribute of the targeted parent. Here are a few examples:

Content of direct parent :

${..}

Contents of parent N+4 :

${../../../..}

Attribute attribute_A of the content of the direct parent :

${../attribute_A}

Attribute attribute_B of the content linked by attribute attribute_A of the content of parent N+2 :

${../../attribute_A.attribute_B}

When using a multivalued clause variable, a join on a multivalued attribute or autoposting for thesaurii, the specified query can be modified before execution to test all expected values. For example, the following query :

my_attribute_A:${../my_parent_multivalued_attribute_A}

 becomes

my_attribute_A:my_parent_attribute_A_value_1 OR my_attribute_A:my_parent_attribute_A_value_2 OR ...

You can add groups that allow you to duplicate only certain parts of queries, rather than the entire query. This means that queries executed a certain number of times are much more efficient. The group is enclosed in braces, preceded by the '#' sign:

#{my_attribute_A:${../my_parent_mutlivalued_attribute_A}} OR {!ametys join=linkContent->my_attribute_B q='%{#{id:"${../my_parent_multivalued_attribute_B}"}}'}

becomes

(my_attribute_A:my_parent_attribute_A_value_1 OR my_attribute_A:my_parent_attribute_A_value_2 OR ...) OR ({!ametys join=linkContent->my_attribute_B q='(id:"my_parent_attribute_A_value_1 OR id:my_parent_attribute_A_value_2 OR ...")'})

There are several rules to know:

  • If there is no group in the clause, the clause itself is considered a group.
  • No variable can be used outside a group.
  • Within a group, the same variable can be used several times.
  • Within a group, you can't use several different variables.

Add clause variables

A clause variable is used to provide a value at extraction runtime. The variable can be used in component clauses using the notation ${myVariable}. This notation will be replaced at runtime by the value supplied.

The Clause variable node contains all clause variables. It is automatically created when the definition file is created.

 In the 'Extraction details' tool, select the Clause variables node and click on the 'Modify' button in the 'Extractions' tab. A dialog box appears, allowing you to add new clause variables or modify existing ones:

   

  • Name: variable name, to be used later in clauses.
  • Type: type of clause variable. This corresponds to the type of value to be supplied when the extraction is executed. You can supply either a list of contents, or a query solr.
    • For the List of contents type: it is possible, but not mandatory, to provide a content type and/or a solr query to restrict the values (contents) entered at runtime.
    • For the solr query type: it is possible, but not mandatory, to provide one or more content types. The solr query entered at runtime will take these types into account

Before version 1.12.0, you couldn't restrict the list of contents using a query solr, you could only provide a content type. In addition, the Query variable type Solr did not exist.

You can add variables by clicking on the '+' button.

Add variables for optional columns

Variables are used to make columns optional. At runtime, the user chooses for each variable whether or not the columns dependent on that variable will be displayed. To make a column dependent on a variable, simply enter the variable name in brackets in the Columns field. Example:

attribute_A (optianalA), attribute_B

The Optional columns node contains all these variables. It is automatically created when the definition file is created.

In the 'Extraction details' tool, select the Optional columns node and click on the 'Modify' button in the 'Extractions' tab. A dialog box appears, allowing you to create one or more variables for the optional columns:

  • Names: variable names for optional columns, separated by commas.

Modifying a node

In the 'Extraction details' tool, select a node and click on the 'Modify' button in the 'Extractions' tab:

A dialog box appears, allowing you to modify the information for the selected node. The fields in the dialog box depend on the node selected.

Delete a node

In the 'Extraction details' tool, select a node and click on the 'Delete' button in the 'Extractions' tab:

After confirmation, the selected node and all its children are deleted.

Save or cancel changes

When you make a change to an extraction, a star is displayed in the name of the corresponding 'Extraction details' tool. You can save the changes you have made to the extraction by clicking on the 'Save' button. from the 'Extractions' tab:

Alternatively, you can cancel these modifications by clicking on the 'Cancel' button in the 'Extractions' tab:

Rename a definition file

In the 'Extractions' tool, select a definition file and click on the 'Rename' button in the 'Extractions' tab:

You can also click on the 'Rename' button in the 'Extraction details' tool.

Delete a definition file

In the 'Extractions' tool, select a definition file and click on the 'Delete' button in the 'Extractions' tab:

Actions to share extractions

Before version 1.7.0

Actions for sharing extractions are available under "Sharing",

and are accessible when an extraction is selected. 

  • The Visibility button changes the visibility of an extraction: 
  • Public  extraction can be modified and/or executed by all users
  • Shared The extraction can only be modified and/or executed by users selected via the "Query rights" button, shown below. 
  • Private extraction can only be modified and executed by the current user. 
Extraction rights

This button is only available if the selected extraction has shared visibility, and opens the "Extraction rights" tool.

Tool

This tool lists users or groups with read and read/write access to the selected extraction. 

Users or groups with read access will only be able to view the extraction, without being able to modify it. 

Users or groups with read/write access will be able to view the extraction, as well as modify it. 

Actions

Extraction rights" tool actions  are available in a "Sharing" tab. 

  • This button is available as soon as at least one category (read or read/write) is selected. 

It allows you to add one or more users to the selected category(ies), and thus add the corresponding right. 

A window opens, allowing you to select the users to whom the corresponding right should be assigned.  

  •  This button is available as soon as at least one category (read or read/write) is selected. 

It allows you to add one or more groups to the selected category(ies), and thus add the corresponding right. 

A window opens, allowing you to select the groups to which to assign the corresponding right. 

  • This button is available as soon as at least one user or group is selected. 

Removes this user or group from the selected category. 

A pop-up window opens to ask for confirmation. 

From version 1.7.0

The "Restrict access" button is available on a directory or extraction.

This button opens the following management tool:  

This same tool can be found by clicking on the "Users, Groups & Rights"/"Assign profiles" button, then selecting the "Extraction" context. 

This tool lets you assign rights to directories or queries, according to the following principles: 

  • I see a folder if :
    • I have the right to write or read on it
    • I have read/write access to a subfolder
    • I have read/write access to a sub-query
    • I have a sub-query that I created myself
  • I can rename a folder if :
    • I have the right to write on it and the direct relative
  • I can delete a folder if :
    • I have the right to write on them, on all the children and on the direct parent.
  • I can move a file if :
    • I have write access on all children, on the direct parent and on the target folder.
  • I can create a folder if :
    • I have write access on all children, on the direct parent and on the target folder.
  • I can add a query if :
    • I have the right to write on the direct relative
  • I can delete/modify a request if :
    • This is my request
    • If I have the right to write on this request and on its direct relative
  • I can move a request if :
    • This is my request, and I have write access to the target folder.
    • If I have write access to this request, its direct parent and the target folder

Summary table:

ID*: internal identifier used in bus messages and buttons

Back to top