Overview
Configuration is provided for establishing connections with KnowBe4 service. The configuration is used in the REST Connection Manager.
Setup
Press 
icon to get more information about the connection parameters.
Obtain data
Use REST Source component to get data from service resource.
Insert data
Use REST Destination component to insert data into service resource.
Quick Start
In this task, we will show you step-by-step how to create a connection to KnowBe4 REST API using COZYROC's REST Connection Manager.
Step 1. Run "Visual Studio" under "Administrator account". Right click on Connection managers Tab and Select New Connection. In Add SSIS Connection Manager scroll down and select Connection managers for REST Connection and click Add.
Step 2. From drop-down menu Configuration select KnowBe4. Set Server to the desired server in the Server URL https://[Server].knowbe4.com/graphql. For Example Accounts on the EU server, located at eu.knowbe4.com, must use the Server URL of https://eu.knowbe4.com/graphql.
Step 3. Provide the value for the parameters Events_Token Reporting_Token PhishER_Token in the grid below
Events_Token parameter is required
Reporting_Token parameter is optional
PhishER_Token parameter is optional
Step 4. Click "Test Connection" to test your connection.
Congratulations! You have now established a connection to your KnowBe4 instance.
In this guide, we will show how to read data from the KnowBe4 service resource using the COZYROC REST Source component.
Step 1. Select an existing "Data Flow task" or create a new "Data Flow Task".
Step 2. Open "SSIS Toolbox" and drag and drop COZYROC "REST Source" component.
Step 3. Double click on the "REST Source" component and select KnowBe4 connection from the combo. Select from available KnowBe4 resources listed in the second combo below.
Optionally you can include extra parameters in the grid below if needed.
Step 4. Click on the "Columns tab" and select KnowBe4 resource columns you want to read.
Step 5. Click Preview to make sure all necessary resource columns are included.
Bravo! You have now learned how to read data from KnowBe4 service.
In this guide, we will show how to write data to the KnowBe4 service resource using the COZYROC REST Destination component.
Step 1. Select an existing "Data Flow task" or create a new "Data Flow Task".
Step 2. Open the "SSIS Toolbox" and drag and drop COZYROC "REST Destination" component.
Step 3. Double click on the "REST Destination" component and select KnowBe4 connection from the combo. Also, select resource action and KnowBe4 resource you want to work on.
Step 4. Click on the "Mapping" tab and map the input columns for the process you are configuring.
If you want to provide input for other resource composite objects, change the input above and map the columns.
Done. You have now learned how to write data into the KnowBe4 resource.
Configuration
Base URL address: https://[Server].knowbe4.com/graphql.
- Token
-
The authentication uses a parameters-based authentication.
The authentication has the following user-defined parameters:
- Events_Token: Required. Specify UserEvents API Token.
- Reporting_Token:
- PhishER_Token:
The following request parameters will be automatically processed during the authentication process:
Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Authentication.
Based on resource template Event.
- [Read] action
-
Endpoint URL address:
/events.Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Events/operation/listEvents.
- [Read single] action
-
Endpoint URL address:
/events/{{=parameters.event_id}}.
The result is extracted from:{{=[response.data]}}.The action has the following user-defined parameters:
- event_id: Required. Specify event identifier.
Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Events/operation/showEventById.
- [Create] action
-
Endpoint URL address:
/events.Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Events/paths/~1events/post.
- [Delete] action
-
Endpoint URL address:
/events/{{=item.id}}.Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Events/operation/deleteEvent.
- id
A key field. Template: ShortText.
- account_id
Template: Id.
- user
Template: UserT.
- external_id
Template: ShortText.
- target_user
Template: ShortText.
- source
Template: ShortText.
- description
Template: ShortText.
- occurred_date
Template: DateTime.
- risk
Field components:
-
Uses template:
ShortText. - Contains the following components: level, decay_mode, expire_date, factor.
-
Uses template:
- metadata
Template: ShortText.
- event_type
Template: EventTypeT.
Based on resource template Event.
- [Read] action
-
Endpoint URL address:
/event_types.Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Event-Types/operation/event_type.
- [Read single] action
-
Endpoint URL address:
/event_types/{{=KnowBe4.UI.EventTypeEditor.getValue(parameters)}}.
The result is extracted from:{{=[response.data]}}.The action has the following user-defined parameters:
- eventType_id: Required. Specify event type identifier.
Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Event-Types/operation/showEventTypeById.
- [Create] action
-
Endpoint URL address:
/event_types.Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Event-Types/paths/~1event_types/post.
- [Update] action
-
Endpoint URL address:
/event_types/{{=item.id}}.Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Event-Types/paths/~1event_types~1%7Bid%7D/put.
- [Delete] action
-
Endpoint URL address:
/event_types/{{=item.id}}.Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Event-Types/operation/deleteEventType.
The resource includes the fields from the EventTypeT template.
Based on resource template Event.
- [Read] action
-
Endpoint URL address:
/statuses.Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Request-Statuses/operation/showStatuses.
- [Read single] action
-
Endpoint URL address:
/statuses/{{=parameters.eventStatus_id}}.
The result is extracted from:{{=[response.data]}}.The action has the following user-defined parameters:
- eventStatus_id: Required. Specify event type identifier.
Documentation: https://developer.knowbe4.com/rest/userEvents#tag/Request-Statuses/operation/showSpecificStatus.
- id
A key field. Template: Id.
- details
Field components:
-
Uses template:
LongText. - Contains the following components: events, failures.
-
Uses template:
- processed
Template: DateTime. A read-only field.
- api_key
Template: ShortText.
Based on resource template Reporting.
- [Read] action
-
Endpoint URL address:
/account.
The result is extracted from:{{=[response]}}.
The result is paginated.The following request parameters will be automatically processed:
-
page:
{{=undefined}} -
per_page:
{{=undefined}}
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Account/paths/~1v1~1account/get.
-
page:
- name
Template: ShortText.
- type
Template: ShortText.
- domains
Template: ArrayOfStrings.
- admins
Field components:
- An array.
- Contains the following components: id, first_name, last_name, email.
- subscription_level
Template: ShortText.
- subscription_end_date
Template: DateTime. A read-only field.
- number_of_seats
Data type: DT_I4
- current_risk_score
Data type: DT_R8
- risk_score_history
The value is gathered from
/account/risk_score_historyaddress. Field components:- An array.
-
Uses template:
RiskScoreHistoryT.
Based on resource template Reporting.
- [Read] action
-
Endpoint URL address:
/groups.Documentation: https://developer.knowbe4.com/rest/reporting#tag/Groups/paths/~1v1~1groups/get.
- [Read single] action
-
Endpoint URL address:
/groups/{{=KnowBe4.UI.GroupEditor.getValue(parameters)}}.
The result is extracted from:{{=[response]}}.The action has the following user-defined parameters:
- group_id: Required. Specify group identifier.
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Groups/paths/~1v1~1groups~1%7Bgroup_id%7D/get.
- id
A key field. Template: Id.
- name
Template: ShortText.
- group_type
Template: ShortText.
- member_count
Data type: DT_I4
- current_risk_score
Data type: DT_R8
- status
Template: ShortText.
- provisioning_guid
Data type: DT_GUID
- risk_score_history
The value is gathered from
/groups/{{=item.id}}/risk_score_historyaddress. Field components:- An array.
-
Uses template:
RiskScoreHistoryT.
- users
The value is gathered from
/groups/{{=item.id}}/membersaddress. Field components:- An array.
-
Uses template:
UserT.
Based on resource template Reporting.
- [Read] action
-
Endpoint URL address:
/phishing/security_tests.Documentation: https://developer.knowbe4.com/rest/reporting#tag/Phishing/paths/~1v1~1phishing~1security_tests/get.
- [Read single] action
-
Endpoint URL address:
/phishing/security_tests/{{=KnowBe4.UI.PhishingEditor.getValue(parameters)}}.
The result is extracted from:{{=[response]}}.The action has the following user-defined parameters:
- pst_id: Required. Specify phishing security test identifier.
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Groups/paths/~1v1~1groups~1%7Bgroup_id%7D/get.
- [Read campaign] action
-
Endpoint URL address:
/phishing/campaigns/{{=parameters.campaign_id}}/security_tests.The action has the following user-defined parameters:
- campaign_id: Required. Specify phishing campaign identifier.
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Phishing/paths/~1v1~1phishing~1campaigns~1%7Bcampaign_id%7D~1security_tests/get.
- pst_id
A key field. Template: Id.
- campaign_id
Template: Id.
- status
Template: ShortText.
- name
Template: ShortText.
- groups
Field components:
- An array.
-
Uses template:
GroupT.
- phish_prone_percentage
Data type: DT_R8
- started_at
Template: DateTime. A read-only field.
- duration
Data type: DT_I4
- categories
Field components:
- An array.
- Contains the following components: category_id, name.
- template
Template: TemplateT.
- landing-page
Field components:
-
Uses template:
Id. - Contains the following components: id, name.
-
Uses template:
- scheduled_count
Data type: DT_I4
- delivered_count
Data type: DT_I4
- opened_count
Data type: DT_I4
- clicked_count
Data type: DT_I4
- replied_count
Data type: DT_I4
- attachment_open_count
Data type: DT_I4
- macro_enabled_count
Data type: DT_I4
- data_entered_count
Data type: DT_I4
- qr_code_scanned_count
Data type: DT_I4
- reported_count
Data type: DT_I4
- bounced_count
Data type: DT_I4
- campaign
The value is gathered from
/phishing/campaigns/{{=item.campaign_id}}address. Field components:-
Uses template:
Id. - Contains the following components: campaign_id, name, groups, last_phish_prone_percentage, last_run, status, hidden, send_duration, track_duration, frequency, difficulty_filter, create_date, psts_count, psts.
-
Uses template:
- recipients
The value is gathered from
/phishing/security_tests/{{=item.pst_id}}/recipientsaddress. Field components:- An array.
- Contains the following components: recipient_id, pst_id, user, template, scheduled_at, delivered_at, opened_at, clicked_at, replied_at, attachment_opened_at, macro_enabled_at, data_entered_at, qr_code_scanned, reported_at, bounced_at, ip, ip_location, browser, browser_version, os.
Based on resource template Reporting.
- [Read] action
-
Endpoint URL address:
/training/store_purchases.Documentation: https://developer.knowbe4.com/rest/reporting#tag/Training/paths/~1v1~1training~1store_purchases/get.
- [Read single] action
-
Endpoint URL address:
/training/store_purchases/{{=KnowBe4.UI.StorePurchaseEditor.getValue(parameters)}}.
The result is extracted from:{{=[response]}}.The action has the following user-defined parameters:
- store_purchase_id: Required. Specify store purchase identifier.
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Training/paths/~1v1~1training~1store_purchases~1%7Bstore_purchase_id%7D/get.
- store_purchase_id
A key field. Template: Id.
- content_type
Template: ShortText.
- name
Template: ShortText.
- description
Template: ShortText.
- type
Template: ShortText.
- duration
Data type: DT_I4
- retired
Data type: DT_BOOL
- retirement_date
Template: DateTime. A read-only field.
- publish_date
Template: DateTime. A read-only field.
- publisher
Template: ShortText.
- purchase_date
Template: DateTime. A read-only field.
- policy_url
Template: LongText.
Based on resource template Reporting.
- [Read] action
-
Endpoint URL address:
/training/policies.Documentation: https://developer.knowbe4.com/rest/reporting#tag/Training/paths/~1v1~1training~1policies/get.
- [Read single] action
-
Endpoint URL address:
/training/policies/{{=KnowBe4.UI.PolicyEditor.getValue(parameters)}}.
The result is extracted from:{{=[response]}}.The action has the following user-defined parameters:
- policy_id: Required. Specify policy identifier.
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Training/paths/~1v1~1training~1policies~1%7Bpolicy_id%7D/get.
- policy_id
A key field. Template: Id.
- content_type
Template: ShortText.
- name
Template: ShortText.
- minimum_time
Data type: DT_I4
- default_language
Template: ShortText.
- status
Data type: DT_I4
Based on resource template Reporting.
- [Read] action
-
Endpoint URL address:
/training/campaigns.Documentation: https://developer.knowbe4.com/rest/reporting#tag/Training/paths/~1v1~1training~1campaigns/get.
- [Read single] action
-
Endpoint URL address:
/training/campaigns/{{=KnowBe4.UI.CampaignEditor.getValue(parameters)}}.
The result is extracted from:{{=[response]}}.The action has the following user-defined parameters:
- campaign_id: Required. Specify campaign identifier.
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Training/paths/~1v1~1training~1campaigns~1%7Bcampaign_id%7D/get.
- campaign_id
A key field. Template: Id.
- name
Template: ShortText.
- groups
Field components:
- An array.
-
Uses template:
GroupT.
- status
Template: ShortText.
- content
Field components:
- An array.
- duration_type
Template: ShortText.
- start_date
Template: DateTime. A read-only field.
- end_date
Template: DateTime. A read-only field.
- relative_duration
Template: ShortText.
- auto_enroll
Data type: DT_BOOL
- allow_multiple_enrollments
Data type: DT_BOOL
- completion_percentage
Data type: DT_I4
Based on resource template Reporting.
- [Read] action
-
Endpoint URL address:
/training/enrollments.Documentation: https://developer.knowbe4.com/rest/reporting#tag/Training/paths/~1v1~1training~1enrollments/get.
- [Read single] action
-
Endpoint URL address:
/training/enrollments/{{=parameters.enrollment_id}}.
The result is extracted from:{{=[response]}}.The action has the following user-defined parameters:
- enrollment_id: Required. Specify store enrollment identifier.
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Training/paths/~1v1~1training~1campaigns~1%7Bcampaign_id%7D/get.
- enrollment_id
A key field. Template: Id.
- content_type
Template: ShortText.
- module_name
Template: ShortText.
- user
Template: UserT.
- campaign_name
Template: ShortText.
- enrollment_date
Template: DateTime. A read-only field.
- start_date
Template: DateTime. A read-only field.
- completion_date
Template: DateTime. A read-only field.
- status
Template: ShortText.
- time_spent
Data type: DT_I4
- policy_acknowledged
Data type: DT_BOOL
Based on resource template Reporting.
- [Read] action
-
Endpoint URL address:
/users.Documentation: https://developer.knowbe4.com/rest/reporting#tag/Users/paths/~1v1~1users/get.
- [Read single] action
-
Endpoint URL address:
/users/{{=parameters.user_id}}.
The result is extracted from:{{=[response]}}.The action has the following user-defined parameters:
- user_id: Required. Specify user identifier.
Documentation: https://developer.knowbe4.com/rest/reporting#tag/Users/paths/~1v1~1users~1%7Buser_id%7D/get.
- id
Template: Id.
- employee_number
Template: ShortText.
- first_name
Template: ShortText.
- last_name
Template: ShortText.
- job_title
Template: ShortText.
Template: ShortText.
- phish_prone_percentage
Data type: DT_R8
- phone_number
Template: ShortText.
- extension
Template: ShortText.
- mobile_phone_number
Template: ShortText.
- location
Template: ShortText.
- division
Template: ShortText.
- manager_name
Template: ShortText.
- manager_email
Template: ShortText.
- provisioning_managed
Data type: DT_BOOL
- provisioning_guid
Data type: DT_GUID
- groups
Template: LongText. A composite field.
- current_risk_score
Data type: DT_R8
- aliases
Template: LongText. A composite field.
- joined_on
Template: DateTime. A read-only field.
- last_sign_in
Template: DateTime. A read-only field.
- status
Template: ShortText.
- organization
Template: ShortText.
- department
Template: ShortText.
- language
Template: ShortText.
- comment
Template: ShortText.
- employee_start_date
Template: DateTime. A read-only field.
- archived_at
Template: DateTime. A read-only field.
- risk_score_history
The value is gathered from
/users/{{=item.id}}/risk_score_historyaddress. Field components:- An array.
-
Uses template:
RiskScoreHistoryT.
- [External]
-
The external fields URL address:
/users. The external fields list is extracted from:{{=_.map( _.filter(_.keys(response), function(name) { return name.indexOf('custom') != -1; }), function(name) { return { name: name }; } )}}.- {{=external.name}}
Template: ShortText.
Based on resource template GraphQL.
- [Read] action
-
Endpoint URL address:
/.
The result is extracted from:{{=utils.ensureArray(response['data'])}}.
The action uses POST method.The action has the following user-defined parameters:
- query: Required. Query statement that will be sent to the GraphQL server.
- variables: Format should be a valid JSON e.g. { "myVar": "myVarValue" }. Optional.
The following request parameters will be automatically processed:
-
application/json:
{{=GraphQL.createCustomQuery(resource, parameters)}}
- [External]
-
The external fields list is extracted from:
{{=GraphQL.getCustomQueryFields(parameters.query)}}.
- [Read] action
-
The result is extracted from:{{=utils.ensureArray(response['data'][resource.name])}}.
- [External]
-
The external fields list is extracted from:
{{=GraphQL.getReadQueryFields(resource.external)}}. - [External]
-
The external fields list is extracted from:
{{=GraphQL.getMutationQueryFields(resource.external)}}.
The external resource list is extracted from: {{=GraphQL.getEntrypointMetadata(GraphQL.entrypointType.query)}}.
Based on resource template GraphQL.
The external resource list is extracted from: {{=GraphQL.getEntrypointMetadata(GraphQL.entrypointType.mutation)}}.
Based on resource template GraphQL.
- [Read] action
-
The result is paginated.The following request parameters will be automatically processed:
-
page:
{{=parameters.iterator}} -
per_page:
{{=parameters.batchSize}} -
_includeUserParameters:
{{=parameters}}
-
page:
- [Read single] action
-
The result is paginated.The following request parameters will be automatically processed:
-
_includeUserParameters:
{{=parameters}}
-
_includeUserParameters:
- [Create] action
-
The action uses POST method.The following request parameters will be automatically processed:
-
_includeUserParameters:
{{=parameters}} -
application/json:
{{=item}}
-
_includeUserParameters:
- [Update] action
-
The action uses PUT method.The following request parameters will be automatically processed:
-
_includeUserParameters:
{{=parameters}} -
application/json:
{{=item}}
-
_includeUserParameters:
- [Delete] action
-
The action uses DELETE method.
- [Read] action
-
Endpoint URL address:
/.
The action uses POST method.The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.PhishER_Token}} -
application/json:
{{=GraphQL.createQuery(resource, parameters)}}
-
Authorization:
- [Create] action
-
Endpoint URL address:
/.
The action uses POST method.The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.PhishER_Token}} -
application/json:
{{=GraphQL.createMutation(resource, parameters, item)}}
-
Authorization:
- [Update] action
-
Endpoint URL address:
/.
The action uses POST method.The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.PhishER_Token}} -
application/json:
{{=GraphQL.createMutation(resource, parameters, item)}}
-
Authorization:
- [Upsert] action
-
Endpoint URL address:
/.
The action uses POST method.The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.PhishER_Token}} -
application/json:
{{=GraphQL.createMutation(resource, parameters, item)}}
-
Authorization:
- [Delete] action
-
Endpoint URL address:
/.
The action uses POST method.The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.PhishER_Token}} -
application/json:
{{=GraphQL.createMutation(resource, parameters, item)}}
-
Authorization:
Based on resource template Base.
- [Read] action
-
The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.Reporting_Token}}
-
Authorization:
Based on resource template Base.
- [Read] action
-
The result is extracted from:{{=response.data}}.The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.Events_Token}}
-
Authorization:
- [Create] action
-
The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.Events_Token}}
-
Authorization:
- [Update] action
-
The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.Events_Token}}
-
Authorization:
- [Delete] action
-
The following request parameters will be automatically processed:
-
Authorization:
Bearer {{=connection.user.Events_Token}}
-
Authorization:
- ShortText
Data type: DT_WSTR ( length 255 )
- LongText
Data type: DT_WSTR ( length 1000 )
- DateTime
Data type: DT_DBTIMESTAMP
- Date
Data type: DT_DBDATE
- Id
Data type: DT_UI8
- ArrayOfStrings
Template: ShortText. A composite field. The gathered value is processed with
{{=value && value.join(',')}}expression.- UserT
Field components:
-
Uses template:
Id. - Contains the following components: id, employee_number, first_name, last_name, job_title, email, phish_prone_percentage, phone_number, extension, mobile_phone_number, location, division, manager_name, manager_email, provisioning_managed, provisioning_guid, groups, current_risk_score, aliases, joined_on, last_sign_in, status, organization, department, language, comment, archived, employee_start_date, archived_at.
-
Uses template:
- TemplateT
Field components:
-
Uses template:
Id. - Contains the following components: id, name, difficulty, type.
-
Uses template:
- EventTypeT
Field components:
-
Uses template:
Id. - Contains the following components: id, account_id, name, description.
-
Uses template:
- GroupT
Field components:
-
Uses template:
Id. - Contains the following components: group_id, name.
-
Uses template:
- RiskScoreHistoryT
Field components:
-
Uses template:
DateTime. - Contains the following components: risk_score, date.
-
Uses template:
Knowledge Base
What's New
- New: Introduced connection.
Related documentation
COZYROC SSIS+ Components Suite is free for testing in your development environment.
A licensed version can be deployed on-premises, on Azure-SSIS IR and on COZYROC Cloud.