Merge pull request #77 from tranpl/master

implement new api methods and bug fixes

README.md

@@ -1,5 +1,5 @@
 [![Travis](https://img.shields.io/travis/cctrbic/redcap-api.svg?style=for-the-badge)](https://travis-ci.org/cctrbic/redcap-api) [![NuGet](https://img.shields.io/nuget/dt/RedcapApi.svg?style=for-the-badge)](https://www.nuget.org/packages/RedcapAPI/1.0.1-beta) [![license](https://img.shields.io/github/license/mashape/apistatus.svg?style=for-the-badge)](https://github.com/cctrbic/redcap-api/blob/master/LICENSE.md)
-
+[![Build status](https://dev.azure.com/cctrbic/redcap-api-library/_apis/build/status/redcap-api-library-ASP.NET%20Core-CI)](https://dev.azure.com/cctrbic/redcap-api-library/_build/latest?definitionId=15)
 
 Project Feedback, using REDCap of course: https://redcap.vcu.edu/surveys/?s=KJLHWRTJYA
 

RedcapApi/Api/Redcap.cs

@@ -133,7 +133,6 @@ public async Task<string> ExportArmsAsync(string token, ReturnFormat returnForma
             }
 
         }
-
         /// <summary>
         /// API Version 1.0.0+ **
         /// Export Arms
@@ -146,7 +145,7 @@ public async Task<string> ExportArmsAsync(string token, ReturnFormat returnForma
         /// <param name="token">The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.</param>
         /// <param name="content">arm</param>
         /// <param name="returnFormat">csv, json [default], xml</param>
-        /// <param name="arms">an array of arm numbers that you wish to pull events for (by default, all events are pulled)</param>
+        /// <param name="arms">e.g. ["1","2"] an array of arm numbers that you wish to pull events for (by default, all events are pulled)</param>
         /// <param name="onErrorFormat">csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'json'.</param>
         /// <returns>Arms for the project in the format specified(only ones with Events available)</returns>
         public async Task<string> ExportArmsAsync(string token, Content content, ReturnFormat returnFormat = ReturnFormat.json, string[] arms = null, OnErrorFormat onErrorFormat = OnErrorFormat.json)
@@ -3173,6 +3172,50 @@ public async Task<string> ExportRepeatingInstrumentsAndEvents(string token, Cont
                 return Ex.Message;
             }
         }
+        /// <summary>
+        /// API Version 1.0.0+
+        /// From Redcap Version 8.10.0
+        /// 
+        /// Import Repeating Instruments and Events
+        /// This method allows you to import a list of the repeated instruments and repeating events for a project. This includes their unique instrument name as seen in the second column of the Data Dictionary, as well as each repeating instrument's corresponding custom repeating instrument label. For longitudinal projects, the unique event name is also needed for each repeating instrument. Additionally, repeating events must be submitted as separate items, in which the instrument name will be blank/null to indicate that it is a repeating event (rather than a repeating instrument).
+        /// </summary>
+        /// <param name="token">The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.</param>
+        /// <param name="data">Note: Super API Tokens can also be utilized for this method instead of a project-level API token. Users can only be granted a super token by a REDCap administrator (using the API Tokens page in the REDCap Control Center).</param>
+        /// <param name="content">repeatingFormsEvents</param>
+        /// <param name="format">csv, json [default], xml</param>
+        /// <param name="onErrorFormat">csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'json'.</param>
+        /// <returns>Repeated instruments and events for the project in the format specified and will be ordered according to their order in the project.</returns>
+        public async Task<string> ImportRepeatingInstrumentsAndEvents<T>(string token, List<T> data, Content content = Content.RepeatingFormsEvents, ReturnFormat format = ReturnFormat.json, OnErrorFormat onErrorFormat = OnErrorFormat.json)
+        {
+            try
+            {
+                /*
+                 * Check the required parameters for empty or null
+                 */
+                this.CheckToken(token);
+
+                var _serializedData = JsonConvert.SerializeObject(data);
+
+                var payload = new Dictionary<string, string>
+                {
+                    { "token", token },
+                    { "content", content.GetDisplayName() },
+                    { "format", format.GetDisplayName() },
+                    { "returnFormat", onErrorFormat.GetDisplayName() },
+                    { "data", _serializedData }
+                };
+                return await this.SendPostRequestAsync(payload, _uri);
+            }
+            catch (Exception Ex)
+            {
+                /*
+                 * We'll just log the error and return the error message.
+                 */
+                Log.Error($"{Ex.Message}");
+                return Ex.Message;
+            }
+        }
+
         #endregion Repeating Instruments and Events
         #region Reports
         /// <summary>
@@ -3476,7 +3519,7 @@ public async Task<string> ExportSurveyLinkAsync(string token, Content content, s
                 return Ex.Message;
             }
         }
-        
+
         /// <summary>
         /// API Version 1.0.0+
         /// Export a Survey Participant List

RedcapApi/Docs/Demographics_TestProject_DataDictionary.csv

@@ -0,0 +1,8 @@
+"Variable / Field Name","Form Name","Section Header","Field Type","Field Label","Choices, Calculations, OR Slider Labels","Field Note","Text Validation Type OR Show Slider Number","Text Validation Min","Text Validation Max",Identifier?,"Branching Logic (Show field only if...)","Required Field?","Custom Alignment","Question Number (surveys only)","Matrix Group Name","Matrix Ranking?","Field Annotation"
+record_id,demographics,,text,"Study Id",,,,,,,,,,,,,
+first_name,demographics,"Contact Information",text,"First Name",,,,,,y,,,,,,,
+last_name,demographics,,text,"Last Name",,,,,,y,,,,,,,
+address,demographics,,notes,"Street, City, State, ZIP",,,,,,y,,,,,,,
+email,demographics,,text,E-mail,,,email,,,y,,,,,,,
+dob,demographics,,text,"Date of Birth",,,date_ymd,,,y,,,,,,,
+file_upload,demographics,,file,"File Upload",,,,,,,,,,,,,

RedcapApi/Interfaces/IRedcap.cs

@@ -943,7 +943,7 @@ public interface IRedcap
         Task<string> DeleteRecordsAsync(string token, string[] records, int? arm);
 
         /// <summary>
-        /// API Version 1.0.0
+        /// API Version 1.0.0+
         /// From Redcap Version 8.2.0
         /// 
         /// Export Repeating Instruments and Events
@@ -956,7 +956,7 @@ public interface IRedcap
         /// <returns>Repeated instruments and events for the project in the format specified and will be ordered according to their order in the project.</returns>
         Task<string> ExportRepeatingInstrumentsAndEvents(string token, Content content = Content.RepeatingFormsEvents, ReturnFormat format = ReturnFormat.json);
         /// <summary>
-        /// API Version 1.0.0
+        /// API Version 1.0.0+
         /// From Redcap Version 8.2.0
         /// 
         /// Export Repeating Instruments and Events
@@ -967,7 +967,20 @@ public interface IRedcap
         /// <param name="format">csv, json [default], xml odm ('odm' refers to CDISC ODM XML format, specifically ODM version 1.3.1)</param>
         /// <returns>Repeated instruments and events for the project in the format specified and will be ordered according to their order in the project.</returns>
         Task<string> ExportRepeatingInstrumentsAndEvents(string token, ReturnFormat format = ReturnFormat.json);
-
+        /// <summary>
+        /// API Version 1.0.0+
+        /// From Redcap Version 8.10.0
+        /// 
+        /// Import Repeating Instruments and Events
+        /// This method allows you to import a list of the repeated instruments and repeating events for a project. This includes their unique instrument name as seen in the second column of the Data Dictionary, as well as each repeating instrument's corresponding custom repeating instrument label. For longitudinal projects, the unique event name is also needed for each repeating instrument. Additionally, repeating events must be submitted as separate items, in which the instrument name will be blank/null to indicate that it is a repeating event (rather than a repeating instrument).
+        /// </summary>
+        /// <param name="token">The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.</param>
+        /// <param name="data">Note: Super API Tokens can also be utilized for this method instead of a project-level API token. Users can only be granted a super token by a REDCap administrator (using the API Tokens page in the REDCap Control Center).</param>
+        /// <param name="content">repeatingFormsEvents</param>
+        /// <param name="returnFormat">csv, json [default], xml</param>
+        /// <param name="onErrorFormat">csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'json'.</param>
+        /// <returns></returns>
+        Task<string> ImportRepeatingInstrumentsAndEvents<T>(string token, List<T> data, Content content = Content.RepeatingFormsEvents, ReturnFormat returnFormat = ReturnFormat.json, OnErrorFormat onErrorFormat = OnErrorFormat.json);
         /// <summary>
         /// Export Reports
         /// This method allows you to export the data set of a report created on a project's 'Data Exports, Reports, and Stats' page.

RedcapApi/Models/RedcapArm.cs

@@ -1,4 +1,6 @@
-namespace Redcap.Models
+using Newtonsoft.Json;
+
+namespace Redcap.Models
 {
     /// <summary>
     /// Arms are only available for longitudinal projects.
@@ -8,10 +10,14 @@ public class RedcapArm
         /// <summary>
         /// Number associated with the event, e.g "1"
         /// </summary>
-        public string arm_num { get; set; }
+        /// 
+        [JsonProperty("arm_num")]
+        public string ArmNumber { get; set; }
         /// <summary>
         /// Name of the event. e.g "event1_arm_1"
         /// </summary>
-        public string name { get; set; }
+        /// 
+        [JsonProperty("name")]
+        public string Name { get; set; }
     }
 }

RedcapApi/Models/RedcapEvent.cs

@@ -1,38 +1,55 @@
-namespace Redcap.Models
+using Newtonsoft.Json;
+
+namespace Redcap.Models
 {
     /// <summary>
-    /// Event for redcap longitudinal projects.
+    /// Event for redcap longitudinal projects and repeating instruments/forms.
     /// </summary>
     public class RedcapEvent
     {
+        /// Name of the Event
+        /// This is required.
+        /// The unique name of the redcap event, usually appended with arm_1 after event name.
+        /// e.g "event_1_arm_1"
+        [JsonProperty("event_name")]
+        [JsonRequired]
+        public string EventName { get; set; }
         /// <summary>
-        /// Name of the event
-        /// </summary>
-        public string event_name { get; set; }
-        /// <summary>
-        /// Arm the event belongs to
+        /// Arm the event belongs to, if any
         /// </summary>
-        public string arm_num { get; set; }
+        /// 
+        [JsonProperty("arm_num")]
+        public string ArmNumber { get; set; }
         /// <summary>
-        /// Days of offset
+        /// Days of offset, if any
         /// </summary>
-        public string day_offset { get; set; }
+        /// 
+        [JsonProperty("day_offset")]
+        public string DayOffset { get; set; }
         /// <summary>
-        /// Minimum(floor) of offset
+        /// Minimum(floor) of offset, if any
         /// </summary>
-        public string offset_min { get; set; }
+        /// 
+        [JsonProperty("offset_min")]
+        public string MinimumOffset { get; set; }
         /// <summary>
-        /// Max(ceiling) of offset
+        /// Max(ceiling) of offset, if any
         /// </summary>
-        public string offset_max { get; set; }
+        /// 
+        [JsonProperty("offset_max")]
+        public string MaximumOffset { get; set; }
         /// <summary>
-        /// Unique event name used to identify this event
+        /// Unique event name used to identify this event, if any
         /// </summary>
-        public string unique_event_name { get; set; }
+        /// 
+        [JsonProperty("unique_event_name")]
+        public string UniqueEventName { get; set; }
         /// <summary>
-        /// Label displayed for this event
+        /// Label displayed for this event, if any
         /// </summary>
-        public object custom_event_label { get; set; }
+        /// 
+        [JsonProperty("custom_event_label")]
+        public object CustomEventLabel { get; set; }
     }
 
 }

RedcapApi/Models/RedcapRepeatInstance.cs

@@ -0,0 +1,19 @@
+using Newtonsoft.Json;
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Redcap.Models
+{
+    /// <summary>
+    /// A single repeat instance in redcap
+    /// </summary>
+    public class RedcapRepeatInstance
+    {
+        /// <summary>
+        /// The instance number that the instrument is repeated, e.g 3, repeated on the 3rd instance
+        /// </summary>
+        [JsonProperty("redcap_repeat_instance")]
+        public int RepeatInstance { get; set; }
+    }
+}

RedcapApi/Models/RedcapRepeatInstrument.cs

@@ -0,0 +1,26 @@
+using Newtonsoft.Json;
+
+namespace Redcap.Models
+{
+    /// <summary>
+    /// Redcap Repeat Instrument
+    /// The instrument that is repeated in a project that has repeating instruments enabled.
+    /// This can support "repeat entire event" or "repeat instruments" mode.
+    /// </summary>
+    public class RedcapRepeatInstrument: RedcapEvent
+    {
+
+        /// <summary>
+        /// The unique instrument/form name that is repeated for the specific event.
+        /// e.g demographics
+        /// </summary>
+        [JsonProperty("form_name")]
+        public string FormName { get; set; }
+
+        /// <summary>
+        /// The custom form/instrument label for this repeating instrument or event.
+        /// </summary>
+        [JsonProperty("custom_form_label")]
+        public string CustomFormLabel { get; set; }
+    }
+}

RedcapApi/Redcap.csproj

@@ -1,49 +1,53 @@
-<?xml version="1.0" encoding="utf-8"?>
-<Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <TargetFramework>netstandard2.0</TargetFramework>
-    <Authors>Michael Tran</Authors>
-    <Company>Virginia Commonwealth University</Company>
-    <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
-    <RepositoryUrl>https://github.com/cctrbic/redcap-api</RepositoryUrl>
-    <PackageProjectUrl>https://github.com/cctrbic/redcap-api</PackageProjectUrl>
-    <Description>This library allows applications on the .NET platform to make http calls to REDCap instances.</Description>
-    <Product>Redcap Api Library</Product>
-    <PackageId>RedcapAPI</PackageId>
-    <Version>1.0.6</Version>
-    <AssemblyVersion>1.0.6.0</AssemblyVersion>
-    <PackageTags>redcap api library</PackageTags>
-    <PackageReleaseNotes>quality of life changes for methods
-updated documents
-bug fixes</PackageReleaseNotes>
-    <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
-    <ApplicationIcon />
-    <OutputType>Library</OutputType>
-    <StartupObject />
-    <NeutralLanguage>en</NeutralLanguage>
-  </PropertyGroup>
-  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
-    <Optimize>false</Optimize>
-    <DocumentationFile>bin\Debug\netcoreapp2.0\Redcap.xml</DocumentationFile>
-    <DebugType>portable</DebugType>
-    <DebugSymbols>true</DebugSymbols>
-    <PlatformTarget>AnyCPU</PlatformTarget>
-  </PropertyGroup>
-  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
-    <DocumentationFile>bin\Release\netcoreapp1.1\Redcap.xml</DocumentationFile>
-  </PropertyGroup>
-  <ItemGroup>
-    <Compile Remove="bin\**" />
-    <EmbeddedResource Remove="bin\**" />
-    <None Remove="bin\**" />
-  </ItemGroup>
-  <ItemGroup>
-    <PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
-    <PackageReference Include="Serilog" Version="2.7.1" />
-    <PackageReference Include="System.ComponentModel.Annotations" Version="4.5.0" />
-    <PackageReference Include="System.ValueTuple" Version="4.5.0" />
-    <PackageReference Include="xunit.extensibility.core" Version="2.4.0" />
-    <Content Include="Models\RedcapMetaData.cs" />
-    <Content Include="Models\RecordStatus.cs" />
-  </ItemGroup>
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <Authors>Michael Tran</Authors>
+    <Company>Virginia Commonwealth University</Company>
+    <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
+    <RepositoryUrl>https://github.com/cctrbic/redcap-api</RepositoryUrl>
+    <PackageProjectUrl>https://github.com/cctrbic/redcap-api</PackageProjectUrl>
+    <Description>This library allows applications on the .NET platform to make http calls to REDCap instances.</Description>
+    <Product>Redcap Api Library</Product>
+    <PackageId>RedcapAPI</PackageId>
+    <Version>1.0.7</Version>
+    <AssemblyVersion>1.0.7.0</AssemblyVersion>
+    <PackageTags>redcap api library</PackageTags>
+    <PackageReleaseNotes>Additional tests for latest release.
+Additional methods include: ImportRepeatingInstrumentsAndEvents
+Older APIs have been deprecated(you can still use them but they'll generate warnings).
+Bug fixes</PackageReleaseNotes>
+    <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
+    <ApplicationIcon />
+    <OutputType>Library</OutputType>
+    <StartupObject />
+    <NeutralLanguage>en</NeutralLanguage>
+    <FileVersion>1.0.7.0</FileVersion>
+    <PackageLicenseUrl>https://github.com/cctrbic/redcap-api/blob/master/LICENSE.md</PackageLicenseUrl>
+    <Copyright>https://github.com/cctrbic/redcap-api/blob/master/LICENSE.md</Copyright>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
+    <Optimize>false</Optimize>
+    <DocumentationFile>bin\Debug\netcoreapp2.0\Redcap.xml</DocumentationFile>
+    <DebugType>portable</DebugType>
+    <DebugSymbols>true</DebugSymbols>
+    <PlatformTarget>AnyCPU</PlatformTarget>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
+    <DocumentationFile>bin\Release\netcoreapp1.1\Redcap.xml</DocumentationFile>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Remove="bin\**" />
+    <EmbeddedResource Remove="bin\**" />
+    <None Remove="bin\**" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
+    <PackageReference Include="Serilog" Version="2.7.1" />
+    <PackageReference Include="System.ComponentModel.Annotations" Version="4.5.0" />
+    <PackageReference Include="System.ValueTuple" Version="4.5.0" />
+    <PackageReference Include="xunit.extensibility.core" Version="2.4.0" />
+    <Content Include="Models\RedcapMetaData.cs" />
+    <Content Include="Models\RecordStatus.cs" />
+  </ItemGroup>
 </Project>